Goal. Serve a fixed, live dashboard to untrusted consumers: they see current data, but they cannot run arbitrary SQL or reach anything beyond the dashboard they were given — while the author keeps a convenient authoring UI that nobody else can drive.
There are three serving modes. Two run client SQL only for the author; the other two never accept SQL from the client at all.
| Authoring | Locked, full UI (A) | Static render (B) | |
|---|---|---|---|
| Entry | anofox_serve(port) / serve <db> |
anofox_serve_dashboards(dir, port[, options]) |
serve --dashboards <dir> |
| Audience | the author, on this machine | untrusted consumers (interactive) | untrusted consumers (static) |
| UI | full builder + editor | real client, editor removed | server-side SVG only |
| What the client sends | SQL (POST /query) |
{dashboard, panel, vars, page} (POST /api/panel) — no SQL |
dashboard id + whitelisted ?param= values |
| Database | the live read-write session / file | private read-only snapshot (refreshable), locked config; optionally one data folder | duckdb -readonly, locked config |
| Bind | loopback only (enforced) | bind option (default 127.0.0.1) |
--bind (default 127.0.0.1) |
| Access control | loopback Host, same-origin, per-server token |
same-origin POST; login via an auth proxy (options.auth); row and column policies (options.policy) |
login via an auth proxy (--auth); no policies |
Available in the from-source build only (duckext/, see
BUILD.md); the community extension is render-only.
The AI assistant (#204) is not available on any served or embedded
page in this release — assistConfig() turns it off for served,
embed and the live backend unconditionally, regardless of
app-config.json. It stays available only on static hosting (mode-free,
no server at all) and on the authoring UI's DuckDB-Wasm path. A real CSP
header (not a meta tag, with nonces and frame-ancestors 'none') for a
future served /assist is a follow-up issue.
Runs whatever SQL the builder sends, against your live data. That is the point, so the protection is about making sure only you can send it:
- Loopback only. The extension always binds
127.0.0.1; theservebin refuses a non-loopback--bindin authoring mode. - Per-server token. A random 128-bit token is generated at start. The URL
that is printed (and opened) carries it once —
http://127.0.0.1:8080/?token=…; the server answers with a redirect that stores it in anHttpOnly; SameSite=Strictcookie (anofox_token_<port>). Every request needs the cookie or anX-Anofox-Tokenheader; otherwise401. - DNS rebinding. The
Hostheader must be a loopback name for this port (127.0.0.1,localhost,[::1]); anything else is403. - CSRF. A request whose
Origindiffers from theHostit was sent to is403— including pages on other localhost ports (cookies are shared across ports, origins are not). Atext/plainform/fetch POST from a web page therefore never reaches the SQL endpoint. - Check, server-side (
/check, #199). The builder's Check button (dashboard --check's own diagnostics) needs a scratch session to run its queries in without touching the live data — DuckDB-Wasm has one (web/lint.js'sscratchRunner), but a live backend has none, so this endpoint runs the whole lint on the server instead:POST /checkwith{"script", "strict", "design", "timeout_ms"}(the bodydashboard --check --strict --no-designwould take, plustimeout_ms— default 30,000, at most 120,000), behind the same token/cookie,HostandOriginchecks as/query. Its queries never run on the live session's own connection: a second connection, opened once at start-up next to the live one, is ATTACHed its own:memory:scratch database per call (switched into withUSE, ahead of the live database onsearch_path, DETACHed after) — aCREATE TABLE/VIEW/MACROorSET VARIABLEthe checked script runs lands there, never on the live database, while the live database's own tables stay readable (an input's or::SELECT_AS's default needs real rows). A hung or slow checked query pasttimeout_msis interrupted (duckdb_interrupt, like the locked server's owntimeout_ms) rather than holding that one connection forever — the interrupted query's own error becomes an ordinary diagnostic, plus one morecheck/timeoutdiagnostic, and the connection is cleaned up and reused normally by the next check. There is only the one check connection, so a second/checkwhile one is still running answers503immediately instead of queuing. Returns{"diagnostics", "ok", "summary", "spans"}, the same shape the browser's own check settles to. Not available on the locked server (anofox_serve_dashboards): that one never accepts SQL from the client at all, checked or not. - No CLI meta commands in the text you send (
servebin). It runs SQL through theduckdbCLI. A body (or--initscript) with a line that starts with.is refused, so.shell,.read,.output, … from the client's own text never reach the CLI. The server feeds each body to its session as a file in a private directory (.read), followed by two end markers that carry a new random nonce per request; that staged file is made read-only once written. This is not a sandbox: authoring SQL already runs read-write with external access as the author, so it can still write.shell …into a config file such as~/.duckdbrcit controls — the refusal only stops a dot command in the request's own text. - One session (
serve <db>, #275). Likeanofox_serve(port), the builder talks to one DuckDB session for the whole run, shared by every tab. What a statement leaves (ATTACH, TEMP tables, views and macros,SET VARIABLE,LOAD,SET,USE) is there for the next one — including a transaction: aBEGINor a failed statement in one tab leaves every tab's queries failing until that session'sROLLBACK. Restartservefor a clean session. The database file stays open, and locked, whileserveruns. If the CLI exits, the next query starts a new session and the error says so. - A round that doesn't finish in
--query-timeout(default 120 s) restarts the session (serve <db>, #304). The one long-lived CLI's stdin is the pipe the server writes every round's staged query to, so a body that reads it (read_csv('/dev/stdin'),COPY … FROM '/dev/fd/0',COPY … FROM STDIN, any case) would otherwise block forever waiting for more of that pipe — and so would any other query that simply hangs. Past the timeout theduckdbchild is killed and the next query starts a fresh session (ATTACH, TEMP objects and variables are gone), the same recovery as the CLI exiting on its own. A literal/dev/stdin,/dev/fd/0,/proc/<pid|self|thread-self>/fd/0or a bareFROM STDIN— case-insensitively, with repeated/and/./path segments collapsed — is refused up front (400) before it ever reaches the CLI, the same way a dot-command is; this fast path is best-effort only (a path built at query time, e.g. string concatenation, is not caught by it) and the timeout is what actually bounds the hang either way. The watchdog that enforces it waits on a channel rather than sleeping the full timeout, so a fast round's watchdog thread exits (and is joined) right away instead of staying parked — a query loop doesn't build up one thread per round — and the session'sduckdbchild is never reaped elsewhere while a watchdog that might still signal it is still running. Unix only:servehas no watchdog on Windows (best-effort there, see the deployment notes), so a hang's only backstop there is the fast path above.--query-timeoutapplies to authoring only; passing it with--dashboardsis a usage error (that server's own--timeoutbounds a query there instead). - The private session directory is cleaned up even if
serveis killed (#304).anofox-session-*(its staged queries) is removed on a normal exit as before, and now also on SIGINT/SIGTERM (Ctrl-C,kill): a signal handler sets a flag a background thread polls, which removes the directory and exits — the default "just die" disposition never ran the Rust destructor that did this, so every kill used to leave the directory (and, if one was in flight, that round's query text) behind. Best-effort; akill -9or a crash still cannot run any cleanup code. - Body limit 4 MiB; authoring results are capped at 1,000,000 rows.
GET/HEAD /assets/<rest>(#522), opt-in. Authoring has no dashboards folder (unlike mode A/B below), so a relative::IMAGE/ markdown image source draws the alt-text placeholder by default. `--assets ` (`serve`) / `options.assets` (`anofox_serve`, same key) names a root directly and turns the route on, behind the exact same token/ loopback/`Host`/same-origin guard as `/query` and `/check` above — there is no separate, weaker path to it. `options.assets` additionally needs `enable_external_access` on (and, if `allowed_directories` is set, the root inside one of them): it reads files with plain `std::fs`, which would otherwise bypass both. Full details, containment and response headers (identical to mode A's own `/d//assets/` below) are in "`GET`/`HEAD` `/assets/` — authoring, opt-in (#522)", next to mode A's own assets route further down this document.POST /assist/v1/messagesand…/count_tokens(#740): the builder assistant's proxy to the model API. The API key stays on the server and never reaches the browser. Opt-in: off unless the server is started with--assist/"assist": true, whatever key its environment holds;--assist-*/assist_*settings without it are refused. It then needs a key (the start fails without one):ANTHROPIC_API_KEYin its environment, or--assist-key-file FILE/options.assist_key_file(a regular file, not a symlink, not readable by group or others, at most 4 KiB). Off, the route is a 404.- Auth: the same token / loopback
Host/ same-origin guard as/query. The proxy adds no auth of its own. - Not an open relay: a request may carry only the fields the assistant
sends (
model,max_tokens,system,messages,tools,tool_choice,thinking,stream,metadata,output_config,cache_control). Tools may only be the assistant's own (list_tables,profile_table,run_sql,check_dashboard,propose_dashboard), with notype(so no server tools) and no field besidesname,description,input_schema,strict,cache_controlandeager_input_streaming. Content blocks may be text, tool use / result and thinking only: no image or document blocks, which can name a URL or a file id.metadata.user_idmust be an opaque id. The model must be on--assist-models(defaultclaude-sonnet-5,claude-opus-5-5), andmax_tokensat most--assist-max-tokens(default 32 000). Anything else is a 400, and nothing is sent upstream. - Headers: no client header is forwarded. The server sends its own
x-api-key, a pinnedanthropic-version,content-typeand a genericUser-Agent, so a client'santhropic-betanever passes. - Upstream:
--assist-base-url/options.assist_base_url(defaulthttps://api.anthropic.com; a company gateway that speaks the same API) must behttps://, orhttp://to a loopback address. The proxy follows no redirects and never uses a proxy from the environment (HTTPS_PROXYwould see the key). Upstream error bodies are never relayed (they can echo the request); the client gets the status and the error type only. - Another provider (#843): with
--assist-provider openai/options.assist_providerthe checked request is translated to an OpenAI-compatible/chat/completionsat--assist-base-url(same URL rules), and the reply back to the Messages shape. The same allowlist, budget, pool and log apply; the models must be listed. Its key is optional and comes fromOPENAI_API_KEYor the key file, sent asAuthorization: Bearer—ANTHROPIC_API_KEYis never read for it, so a Claude key in the environment never reaches a local model or gateway. - Cost: an hourly budget of tokens of every kind per server
(
--assist-budget-tokens-per-hour, default 2 000 000) answers 429 once it is used up.count_tokensis free and not counted. At most two calls run at once (503 beyond that), each on its own thread, so a minute-long stream never holds the authoring worker/queryruns on. - Log:
--assist-log PATH|stderr/options.assist_logwrites one JSON line per call:ts,endpoint,model,status, the four token counts,request_id,ms,complete. No prompt, SQL or key, unless--assist-log-content/options.assist_log_contentadds the request body for an audit. - The extension: the proxy calls out of the process and reads its key
file and writes its log with plain
std::fs, past DuckDB's own lockdown. On a session withenable_external_access = falseit stays off:anofox_serverefusesassist_*options there, and a key in the environment alone only gets a note in the result. Withallowed_directoriesset, the key file and the log must be inside one of them. Whoever can callanofox_servecan also setassist_base_urlto their ownhttps://host and so receive the key. A session with external access can read the process environment anyway (getenv,/proc/self/environ), so this is no new exposure. Still: never putANTHROPIC_API_KEYin the environment of a process that runs SQL you don't trust. - The builder: with the proxy on,
index.htmlcarrieswindow.__anofoxApp.assistant = {"enabled": true, "transport": "serve", …}(no key), and its CSP also allows the three modules DuckDB-Wasm's+esmbuild imports (apache-arrow,tslib,flatbuffers, pinned on jsDelivr, asdashboard --site's): the page loads DuckDB-Wasm for the assistant's locked engine only. The engine is filled from the live session through/querywith a fixed set of read statements (the catalog,DESCRIBE,count(*),SELECT *withLIMITor a reservoir sample), never model SQL. Views are copied only when the editor's SQL names them (or Explore's entry came from one): a view runs its whole body on the server's single authoring worker (#742). Rows arrive as the server's JSON text and are typed by DuckDB in the engine (from_jsonagainst the described types, one prepared statement), so they can't add SQL. - A locked server (
anofox_serve_dashboards,serve --dashboards) never routes/assist/v1/*(always 404), andserve --dashboardsrefuses the--assist-*flags. (/assist/<file>outsidev1/is the UI's own code,web/assist/, served as before.)
- Auth: the same token / loopback
SELECT anofox_serve_stop(port) stops an extension server.
Serves the real browser client for every .sql file in dir
(/ lists them, /d/<id> opens one; ids are restricted to [A-Za-z0-9_.-]).
The server owns the SQL. The dashboards are planned on the server at startup; the client never sends SQL. To run statement n of dashboard id it POSTs
{"dashboard": "sales", "panel": 3, "vars": {"region": "EU"},
"page": {"limit": 10, "offset": 20, "sort": "Region", "desc": false, "filter": "app"}}varsvalues must be JSON strings, numbers, booleans,nullor flat lists of those; they become typed SQL literals ('EU',5,TRUE,['a','b']) inSET VARIABLE <name> = <literal>; names must be identifiers. Objects, nested lists, NUL bytes and oversize values are rejected — there is no way to turn a value into an expression or a subquery.page(for::PAGEDtables) is structural: the server builds theCOUNT(*)/ORDER BY/LIMIT/OFFSETquery itself (and the statistics, column-profile and distinct-values queries); column names are quoted as identifiers and the full-text filter and column-filter values are bound as prepared-statement parameters.- Unknown fields, dashboards or panels are rejected (
400/404). There is no/queryendpoint (410). - Every statement of every dashboard is checked with DuckDB's own parser at startup (exactly one statement each); panels execute as single prepared statements.
Read-only, locked-down snapshot. At startup the server copies the session's
databases (COPY FROM DATABASE) into a private, randomly named 0700
directory and opens them in a separate DuckDB instance:
- every attached DuckDB database (not just the current one) is re-attached
READ_ONLYunder its original name; non-DuckDB catalogs (Postgres, SQLite, …) are not snapshotted and are reported as warnings — expose what you need through tables in a DuckDB database (pass'{"attach": false}'to snapshot only the current database); - extensions loaded in the session,
-- @load <ext>header lines andoptions.loadare loaded first; - then
enable_external_access = false(no file or network access —COPY … TO,read_text/read_csv,ATTACH,INSTALL,LOADare all refused), extension auto-install/auto-load and community extensions are off, andlock_configuration = true, so no statement can undo any of it; - on unix the snapshot files are unlinked as soon as they are attached (the open
handles keep working); the directory is removed when the server stops
(
anofox_serve_stop) or a start fails. On Windows the files remain until stop.
Refreshing the snapshot. The snapshot is taken at startup and can be rebuilt while the server runs — no restart, no failed requests:
options.refresh_srebuilds it every n seconds in the background;SELECT anofox_serve_refresh(port)rebuilds it now (from the session that started the server, so it sees that session's committed data) and returns once the new one serves. Rebuilds never overlap: an on-demand refresh waits for a running one, the interval refresher skips its turn.- The swap is atomic: a request takes the current snapshot when it starts and finishes on it; later requests get the new one. The old snapshot (its DuckDB instance and its directory) is closed and deleted when its last request ends.
- Each snapshot has its own result cache, single-flight and supersession table, so nothing is cached, shared or cancelled across snapshots; the ETags carry the snapshot's epoch.
- A failed rebuild leaves the current snapshot in service; the error goes to
the log (and to the caller of
anofox_serve_refresh). GET /healthzreportsversion(the build version, #216),epoch(1 at start, +1 per refresh),snapshot_age_s,refresh_s,refreshingandrefresh_failed(no error text —/healthzis public), andlimits: the effective limits (threads,max_queries,max_rows,max_response_bytes,max_inflight_bytes,cache_bytes,timeout_ms,memory_limit,duckdb_threads) and their use (queries_running,queries_waiting,inflight_bytes,inflight_peak_bytes,refused_inflight,refused_queries). Withauth, a caller that is not signed in through the proxy gets only{"status":"ok"};version(like the rest of this body) appears only withoutauth, or for a caller signed in with no dashboard scoping.- While a rebuild runs, the old and the new snapshot both exist: plan for twice the snapshot's disk and memory.
There is no HTTP endpoint for refreshing: it is a SQL call in the serving session (or the interval), so no viewer can trigger one.
A live data folder (options.data). Data that is too large or changes
too often to copy at every refresh — e.g. a folder with one parquet directory
per forecast run — can be read in place:
SELECT anofox_serve_dashboards('dashboards', 8095,
'{"data": "/srv/runs", "path_vars": ["run"]}');-- a panel: the run is picked by a variable (a dropdown, a ?v.run= link, …)
SELECT ds::XAXIS, yhat::LINECHART
FROM read_parquet(getvariable('anofox_data') || '/' || getvariable('run') || '/forecast.parquet');- The folder (canonicalised: no
..or symlink in the configured path) is the only path the snapshot instance may open — DuckDB'sallowed_directorieswithenable_external_access = falseandlock_configuration = true. DuckDB refuses any path outside it, including…/run/../../etc. - Keep it narrow. Every viewer can read every file in it. The server
refuses
/, top-level system directories (/etc,/home,/tmp,/usr,/var, …) and any folder that contains the home directory or the temp directory (where the snapshots live); point it at the folder that holds the served data and nothing else. - Each request gets
SET VARIABLE anofox_data = '<folder>'after the viewer's variables; a viewer can't setanofox_data(400). path_varslists the variables whose values become path segments: each value must be a plain name —[A-Za-z0-9_.-], not starting with.(so not.,..or a hidden file), no/— a non-negative integer, ornull; anything else is400before any SQL runs.- Read-only — make it so in the OS. DuckDB has no read-only form of
allowed_directories: a statement that writes (COPY … TO,EXPORT,ATTACH, …, or anything that runs one:EXPLAIN ANALYZE,PREPARE/EXECUTE) could write into the folder. The hard guarantee is the operating system's: mount the folder read-only into the server (-v /srv/runs:/srv/runs:ro, a read-only bind mount) or give the server's OS user read permission only. - On top of that, with
dataset the server only starts if every dashboard statement is classified as harmless by DuckDB's own parser (json_serialize_sql, which parses without running and accepts onlySELECTstatements): panels must be queries (SELECT,WITH,FROM,VALUES, set operations; aPIVOTonly as a subquery with itsIN (…)values listed), and setup statements must be queries,SET VARIABLE <name> = <expression>orCREATE [OR REPLACE] TEMP TABLE|VIEW <name> AS <query>with a query that passes the same check (the same classifier the access policy uses). Everything else —EXPLAIN,PREPARE,EXECUTE,CALL,PRAGMA,COPY,INSERT, macros, … — fails the start. The check needs DuckDB'sjsonextension (loaded into the snapshot automatically; without it the server refuses to start). -- @requirespaths (DOCS, Not available) are checked on the server before a statement runs: a setup statement whose input is missing is skipped, a panel answers400optional input missing: no files found …, which the page shows as Not available (also under an access policy: the message carries no data). The rule for a path:${name}takes the request's value of a server-side variable only:anofox_data, apath_varsvariable (already a plain name), a credential's locked variable, a login claim, or one the dashboard's own statements set (SET VARIABLE rd = getvariable('anofox_data') || '/' || getvariable('run')). A variable the viewer sets that is none of these, or an unset one, is not expanded: that alternative counts as missing.- Patterns only from the author's text. A dashboard variable can carry
a viewer's value (
… || getvariable('q')with a freeq), so a variable's value containing a pattern character (*,?,[,],{,}) is refused: that alternative counts as missing. Patterns written in the@requiresline itself (*/forecasts.parquet) work. - The expanded path, resolved against the folder when relative, must stay
inside it: no
..segment, no~, no URL, no backslash or control character, no absolute path outside the folder — such an alternative counts as missing without touching the file system (the log says why). - Matches are confined too.
glob()lists through a symlink that points out of the folder (DuckDB refuses only the read), so the server resolves the matches one by one (at most 1,024 per pattern, stopping at the first) and counts only one whose real path is inside the folder. A pattern whose first 1,024 matches all lead out of the folder counts as missing (fails closed; the log says so). - Any error of the check (a refused path, a glob DuckDB rejects, a timeout, a request superseded mid-check) counts as missing for that request; the details go to the server log only, never to the viewer.
- Definite answers (also "missing") are remembered for 5 seconds per expanded path (at most 4,096), so a recursive pattern is not rescanned by every request. A failed or interrupted check is never remembered, so no viewer can make a file "missing" for the others. The memory is shared: from the response time a viewer may tell whether someone checked the same path in the last 5 seconds (as with the panel cache) — only for paths that viewer can build themselves.
- The viewer learns only available / not available, about files in the folder, which every viewer may read anyway. Without a data folder the snapshot can open no files, and nothing is checked in advance: the statement's own error decides, as before.
- A tab's
@requires(above a::TAB/::SUBTAB) applies to every panel in its section, decided where the tab stands (with the variables set above it, as the page decides): the tab's statement and each of its panels answer Not available when it is not met, so a hidden tab's panels never run — also when a viewer asks for them directly. Setup statements in the section run as before (only their own@requirescan skip them), and so do chrome directives (::THEME,::ASOF, …), which apply to the whole dashboard wherever they sit: keep them above the first tab. At runtime a viewer learns from a hidden tab only what a panel's Not available tells: whether the tab's files exist, by the same rule and check. Hiding a tab is presentation, not secrecy: the served page carries the dashboard's SQL, so its source still lists the tab, its@requireslines and its panels' SQL (never the data folder's path). - A
::VIEWalternative's@requires(#214) is gated the same way, as a third level under::TAB/::SUBTAB: a direct request for a hidden alternative's marker or any of its panels answers Not available, whoever asks, and the group's other alternatives are unaffected. Which alternative a viewer is looking at is never sent to the server — it is not a DuckDB variable, never part of an/api/panelbody and never part of a cache key, so?view.<id>=in the URL is a client-only bookmark: the script-free server ignores it (it reads only declared@params), and a locked server's response to/d/<id>does not change with it. Showing one alternative by default is presentation, not secrecy: a non-hidden alternative's panels can be requested directly whether or not it is the one currently shown, exactly like a shown tab's — they carry only data the viewer may already read, gated by the same scope, claims,@varsand policy as any other request. - A viewer can skip a setup statement that carries
@requires(by picking a run without the file). Never guard a statement that narrows what a viewer sees with it — neither a statement that reads no file (dashboard --checkwarns:requires/on-setup) nor one that reads a file and filters rows (CREATE TEMP VIEW v AS … WHERE r IN (SELECT … FROM read_csv('allowed.csv')): no warning, the lint can't tell). Access policy views are unaffected: the server creates them before any dashboard SQL.
- Error messages sent to viewers show the folder as
<data>; the log keeps the full path. - Files appear live: a new run is readable as soon as it is written, without a
refresh. Parquet footers are cached across requests (
parquet_metadata_cache, set by the server and locked) — and kept in RAM well past whatmemory_limitcounts for them, bounded only by the footer sizes of the files the panels can reach and dropped on a refresh (deployment.md§6). DuckDB re-checks each file's size and modification time (to the second) before using a cached footer: publish a run by writing a new file and renaming it into place (mv), which is always read fresh. A file overwritten in place at the same size within the same second, or with its mtime restored, can be read with its old footer until a refresh. The result cache does not see file changes — runs that are rewritten in place need a refresh (which starts a new cache) orcache_mb: 0. - Views in the session over files in the folder (
CREATE VIEW v AS SELECT … FROM read_parquet('/srv/runs/…')) are copied into the snapshot as views and read the files live too. - Every viewer can read every file in the folder (by any
path_varsvalue): serve one folder per audience. (DuckDB 1.5 resolves symlinks, so reading through a link inside the folder that points outside it is refused too. Aglob()pattern still lists such a file's name: keep links out of the folder, or don't give panels a viewer-chosen pattern. The server's own@requirescheck counts only matches inside the folder, see above.)
The served nav keeps path_vars across dashboards (#407). Clicking
another dashboard in the served nav (web/app.js's .served-nav, injected
whenever 2+ dashboards are served or nav_picker is set) carries the
current value of every path_vars variable along — /d/monitor_features?v.model=car_price_unlabelled —
so switching pages doesn't fall back to the target's own default:
- The server tells the page which variables are
path_vars(window.__served.pathVars, config, not secret — every viewer already knows the server runs with a data folder from the dashboard's own SQL). The page reads the current value of each fromdpVars(whatever a::DROPDOWN/::BUTTONSbound to it, or thenav_pickerbelow, last set) and appends it to every nav link'shrefas?v.<name>=<value>— real hrefs, kept current on every run (syncUrlState→refreshServedNavHrefsinweb/app.js), not just a click handler, so a middle-click / "open in new tab" carries it too. A variable with no value yet is left off the link; the target then falls back to its own default, same as opening it fresh. - Only
path_varsvalues are ever carried — never another viewer input, a selection or a filter — and they are already validated server-side on every request regardless of where they came from (check_path_values, above): the client only URL-encodes them, it adds no new trust boundary. - A target dashboard that doesn't read a given
path_varsname simply ignores it:/api/panelaccepts any well-formed variable name (parse_panel_requestonly checks it's an identifier and not reserved, never that this dashboard uses it) and a panel is sent only the variables its own dependency analysis says it reads (#210) — so an unused?v.<name>=on the URL, or in the request body, is dead weight, not a400. (A dashboard that restricts viewer variables with its own-- @varsis the one exception: list the path variable there too, or a carried-over value is silently dropped for that dashboard, same as any other viewer input it doesn't allow.) - A
path_varsname a scoped credential locks (an embed link'svars) is never carried (security review of #410, M1):window.__served.pathVarsleaves it out (served_index,var_locked). Its value always wins over whatever a nav link, the viewer ornav_pickerwould otherwise set (Scope::lock_vars,locked_panel), so carrying it would be pointless — and, fornav_pickerbelow, worse than pointless. serve --dashboards(the script-free static render, mode B) has nopath_varsordatafolder at all — it whitelists literal-- @paramvalues instead, a different mechanism — and no persistent cross-dashboard nav bar either (only the/list page,page::landing): there is nothing to carry a value across there. This note exists so a futuredata/path_varson that server isn't assumed to inherit this nav behaviour for free.
A nav-bar picker for a path_vars variable (nav_picker, #407). Every
per-model dashboard repeating the same ::DROPDOWN is instead one dropdown
in the nav bar that sets the variable for every page:
SELECT anofox_serve_dashboards('dashboards', 8095, '{
"data": "/srv/models", "path_vars": ["model"],
"nav_picker": {"var": "model", "label": "Model",
"sql": "SELECT model_id, title FROM models ORDER BY title"}
}');varmust be one ofpath_vars— refused at start otherwise (options.nav_picker(s): '…' must be one of options.path_vars).sqlis author/config text, run on the server — never from the viewer. It must be exactly one query, checked the same way everydata-folder statement is (json_serialize_sql, SELECT-only), and must return exactly two columns,(value, label); anything else refuses the server start. It runs once per snapshot (at startup and on every refresh, like a dashboard's own setup) on the locked, read-only snapshot instance, withanofox_dataset and no viewer context at all — no claims, no viewer variables, the same result for every viewer, never re-run per request. Keep its own text free of viewer-chosen values for the same reason a setup statement should be (there is none to use here).- Every
valueit returns is checked against the exact rule apath_varsvalue must already satisfy ([A-Za-z0-9_.-], not starting with., or a non-negative integer) — a row that fails is dropped and logged, never sent to a page. This is the same rule the server enforces on every/api/panelrequest regardless of where a value came from, so a picker value can never reach the server as anything but what a hand-typed?v.<var>=could already send. nav_pickerrefuses to start together withoptions.policy. The access policy rewrites dashboard statements only (Enforcer::rewrite_script);nav_picker.sqlruns directly, outside that rewrite, so it would silently read past the policy's row and column rules for whatever table it queries. Rather than guess at a viewer scope to run it under, the server refuses the combination outright — remove the policy, or don't usenav_picker. (It has no such conflict withauthalone, or with"policy": "none": those already trust every dashboard panel to filter on the claims itself, andnav_picker.sqlis author text of the same trust level.)- Up to 2,000 options, each label at most 200 characters — the whole list is
inlined into every served page (
window.__served.navPicker), not fetched lazily; a longer result refuses the server start (keep the picker's list short, or filter it insql). nav_picker's option list is the same for every viewer who can open a page with it on — there is no per-viewer filtering of it, by claims or otherwise (nav_picker.sqlruns once per snapshot, before any viewer's request even exists — see above). Don't usenav_pickeron a variable whose values themselves are confidential per viewer beyond what a credential's own scope already covers (e.g. one tenant's model names that another tenant must never see): filter that in the dashboards' own SQL via the claims instead, or leave that variable offnav_pickerand keep its own::DROPDOWN/::BUTTONS, which is data the request already decided this viewer may read.nav_pickeris omitted entirely for a credential that locks itsvar(security review of #410, M1 — an embed link'svars): the locked value always overrides whatever the picker would otherwise set (Scope::lock_vars,locked_panel), so showing it would both do nothing for that viewer and disclose every other option's value — e.g. every tenant's model name — to a credential that can only ever end up on its one locked tenant.served_indexchecks this (var_locked) the same way it decides whether to carry the variable on a nav link, above.- The nav renders it with
document.createElement/textContent(renderNavPicker,web/app.js) — neverinnerHTML— so a label can hold arbitrary text without needing its own escaping, and the CSP header below still allows no inline handlers (onchangeis attached in script, like every other control). Choosing a value runsSET VARIABLE <var> = '<value>'and a re-run (makeControl's own pattern), so the panels that depend on it re-run exactly as a::DROPDOWNchange would; the part-2 nav links above then pick up the new value on the nextsyncUrlState. serve --dashboardshas nonav_pickereither, for the same reason it has nopath_vars.
Several pickers, and a date-range picker type (nav_pickers, #556).
options.nav_picker (the bare object above) is still accepted unchanged —
internally a one-element list. options.nav_pickers is a list of pickers,
drawn left to right in the nav bar; the two keys may not both be set, and
at most 8 pickers are accepted (each is inlined into every served page, the
same reasoning as the 2,000-option cap below). Each entry has a "type":
"dropdown" (the default — today's shape, var/sql/label) or
"daterange", a global time window:
"nav_pickers": [
{"type": "daterange", "vars": ["view_from", "view_to"], "label": "Time window",
"sql": "SELECT min(end_date)::DATE, max(end_date)::DATE FROM read_parquet(getvariable('anofox_data') || '/*/chunks.parquet')",
"presets": ["last 7d", "last 30d", "last 90d", "all"]},
{"var": "model", "label": "Model", "sql": "SELECT model_id, title FROM models"}
]varsis[from, to]— exactly two distinct variable names, both required to be inpath_vars(refused at start otherwise, the same rule a dropdown'svarfollows).sqlis optional; when given, it is the same trust level and run-once cadence as a dropdown's — author/config text, never from the viewer, run once per snapshot (startup + every refresh). It must return exactly one row of two columns,(min, max), both real calendar dates withmin <= max— anything else refuses the server start. Withoutsqlthe picker is two plain, unbounded date inputs (no presets: see below).presetsnames entries of a fixed vocabulary —"last 7d","last 30d","last 90d","all"— an unknown name refuses the server start. Each is computed from thesql's ownmax, never wall-clocktoday(), so a snapshot always answers "last 7d" the same way regardless of when a viewer opens the page:"last Nd"is the N calendar days ending onmaxinclusive, clamped up tominif the data doesn't reach back that far;"all"is(min, max).presetsneedssql(refused at start otherwise — there is nomaxto compute them from).- Request-time validation beyond the generic
path_varsshape check (check_path_valuesalready acceptsYYYY-MM-DD— digits and dashes are a valid plain name): each ofvarspresent on a request must be a real calendar date (parse_iso_date;2026-02-30is refused,400), and when both halves are present together,frommust not be afterto(400). A value outside the picker's own[min, max](when it hassql) is clamped, not refused — those bounds are an author-chosen display range, not a security boundary, the same posture a calendar widget's ownmin/maxattributes would take. - The policy conflict above extends to any picker that actually has
sql(a dropdown always does; adaterangeonly when given one) — adaterangewith nosqlhas nothing that would bypass the policy, so it may be combined with one. - The same credential-lock and render rules apply: a
daterangeis omitted entirely if either of its two variables is locked by a scoped credential, and the nav builds it withdocument.createElement/textContent(two<input type="date">, preset buttons, an explicit "Apply" button, a "Clear" button, a status hint — batched into bothSET VARIABLEs + one re-run so the server is never asked to validate one half of the pair against the stale value of the other) — no inlineonchange/onclickattributes (the CSP has no'unsafe-inline'/'unsafe-hashes'forscript-src; #570 is the bug that pattern avoids). "Clear" sendsSET VARIABLE … = NULLfor both —clamp_daterange_valuestreats a NULLpath_varsvalue as "no value" (skips the date check and the clamp), so this is the one way back to an unfiltered dashboard once a window has been set; there is no sentinel date for "unset". With only one side filled, Apply fills the other from the picker's ownmin/max(its fullsql-computed range) when it has one, else it stays disabled with a hint — client-side convenience only, the server still re-checksfrom <= toand re-clamps regardless. - A credential that locks a
daterangevariable to a value that isn't a real calendar date 400s on every panel request for that dashboard (the clamp checks locked values too, the same as a viewer-sent one) — a config mistake to catch at credential-minting time, not something the server works around. dashboard --site(the static export) accepts the singularnav_pickerwith an explicit"type": "dropdown"(the same as omittingtype— it's just the default), so one options file parses the same way for--siteand foranofox_serve_dashboards. A singularnav_pickerwith"type": "daterange", andnav_pickers(plural) under either type, are both refused with a clear "needs the locked server" message — a static site has no server to run the daterange Apply/clamp round trip through.
Content-Security-Policy header (#252). Every HTML page of the locked server
(the dashboard page, the / list, the login pages), of dashboard serve and
of the authoring servers carries a
Content-Security-Policy response header, not just a meta tag:
default-src 'none';- scripts only from the server itself, the pinned DuckDB-Wasm and KaTeX CDN paths, and the server's own inline scripts, each with a fresh random nonce per response;
- images also from any
https:URL (a dashboard's images, the app logo); object-srcandframe-srcare'none';base-uriandform-actionare'self'(sign-out and the script-free pages' forms post to the server).frame-ancestors:'none'(no framing) unless anembedlogin is configured. Embed links are meant to be framed, so withembedthe server sends noframe-ancestorsunless you list the sites that may frame the pages:frame_ancestors: ["https://app.example.com"]. Each entry is anhttps://host[:port]origin, a loopbackhttp://127.0.0.1[:port]orhttp://localhost[:port](a local host page while developing),'self'or'none'. Set it whenever you use embed links:<anofox-dashboard>talks only to these origins.
Per-request isolation and limits.
- A fresh connection per request: one viewer's variables or temp objects never
leak into another's. Setup statements (
CREATE TEMP …) of the dashboard are re-run per request; only TEMP objects can be created (the data is read-only), so materialise anything heavy before serving. ACREATE TEMP TABLE … ASin setup is rebuilt on every connection that runs the setup (without warm connections: every panel request, #387); preferCREATE TEMP VIEW(dashboard --check <folder>warns:folder/setup-table). - Warm connections (
warm, #388). After a clean panel request, its connection, setup already run, waits idle for the next request with the same key. The key is the viewer's login (claims, and with them a policy's per-viewer views), the dashboard, how far into its setup the panel sits, every credential-locked variable, and the values of the request variables that setup reads (the #210 analysis; every variable when it can't tell). So only a request whose fresh connection would end in the same state gets one. On reuse the server resets the variables the previous request set and this one doesn't, sets this request's, and runs the setup's ownSETs again. A connection is never kept after an error, a timeout, a superseded request or a failing setup statement, nor for a panel with a-- @requireson the way (that check depends on files). At mostwarmconnections are kept (default:threads;0= off; least recently used first out). They belong to the snapshot, so a refresh drops them. Each holds its setup's TEMP tables in memory: countwarm× the largest setup table againstmemory_limit. Like a cache hit, a reused connection answers faster. Since the key includes the login, that tells a viewer only about their own earlier requests (or, withoutauth, that someone asked with the same values). - Materialized setup (
-- @materialize, #727). A setup statementCREATE [OR REPLACE] TEMP TABLE t AS <query>with a-- @materializeline above it runs<query>once into a table of the server's own in-memory catalog (__anofox_mat, attached before the lockdown; the dashboards are the server's, viewers send no SQL), and each connection that needs it getstas a copy. Panel requests needing a result that is being built wait for it (within theirtimeout_ms), so a page's panels — after a save, all of them at once — run the query once, not once each. The key: the dashboard, the statement, every credential-locked variable and the values of the request variables the setup up to it reads; a state-enabled dashboard's generation and the saved tables' change-log generation; the viewer's login only for a state-enabled dashboard or setup that reads a claim (or can't be analysed) — otherwise one result serves every viewer, as the same SQL with the same values would compute anyway. Off under an access policy (its views differ per viewer) and past a-- @requires. At most 16 results are kept per snapshot (least recently used out, dropped with it on a refresh); count them againstmemory_limitbeside the warm connections' copies. A failed build or copy falls back to running the statement as written. Arandom()in the query is drawn once per result, so every panel sees the same draw. Unlike the panel cache and warm connections, a result shared between logins answers one viewer faster because another asked with the same values: withauththat tells a viewer that someone did (not who, nor any row they couldn't compute themselves). - Options (third argument, JSON):
max_rows(default 100,000 — exceeding it is an error, not a silent truncation),timeout_ms(default 30,000 — enforced withduckdb_interruptfrom a watchdog),max_body_bytes(default 64 KiB),threads(HTTP worker pool = concurrent requests, default 4),warm(see above),frame_ancestors(see below),cache_mb(see below),attach,load,hosts(see below),refresh_s,data,path_vars,nav_picker(see above),auth,log,log_vars(see Login via an auth proxy),policy(see Row and column policies), and for deployment:bind— listen address, default127.0.0.1."0.0.0.0"(or"::") is for containers and replicas behind a load balancer. A specific address is also accepted as aHost; other names still needhosts.memory_limit— DuckDBmemory_limitof the snapshot instance ("2GB","50%"). The default is DuckDB's 80 % of RAM, shared by all queries.duckdb_threads— DuckDBthreadsof the snapshot instance, shared by all queries. The default is the number of cores.max_queries(default 4) — panel queries running at once. Others wait for a slot (up totimeout_ms, then503withRetry-After); cache hits and requests that join an identical running query don't need one.max_inflight_mb(default 256) — results held outside DuckDB at once, from their first row until their response is written. A request that would exceed it answers503withRetry-After(the first 256 KiB of every request always pass). The browser retries a503twice.max_response_mb(default 32, at mostmax_inflight_mb) — one response; a larger result is an error (413), likemax_rows.max_asset_bytes(default 5 MiB, bytes not MiB, also clamped tomax_inflight_mb) — one file read from the dashboards folder'sassets/subfolder (GET /d/<id>/assets/<rest>, #514 — see "Images in dashboards" below); over it,404.search_path— where the panels' unqualified names resolve:"warehouse","warehouse.sales", or several, comma-separated (the first isUSEd). The default is the serving database's default database: aUSEin the SQL that starts the server does not reach the server, so pass it on withjson_object('search_path', current_database() || '.' || current_schema()). Withattach: false, the databases it names are snapshotted. With an access policy it must name one database (itsmainschema), where the policy resolves names.app— the landing page's header:{"name": "…", "tagline": "…", "logo": "https://… | data:image/…", "favicon": "…"}(the app-bar settings ofanofox_serve;name_visible: falseshows the logo alone). Without it the page is titled Dashboards.charts_as_tables: true(boolean only — #403) is a sibling key with no bearing on the header: an installation default for a viewer's never-set initial "Charts as tables" state (web/app.js'sdpAsTables). It never overrides a viewer's own explicit choice (their remembered toggle, or a dashboard link's?tables=) and never forces a dashboard's own in-page bar on (that stays-- @astables on/ the toolbar's ⋯ menu, #401). Itsfaviconis also every dashboard page's icon, unless a dashboard sets its own::FAVICON.css_file— the operator's stylesheet (#773), linked after the theme on every page. See Your own look.plugins— runtime WebAssembly plugins, a list of.wasmpaths the operator names (#1213; extension builds with thepluginsfeature), loaded at start, sandboxed (no imports, fuel, 64 MiB).plugin_assets(true) also serves their browser files, which run in the page outside the sandbox. See docs/modules.md, Plugins.serve --dashboards(mode B, script-free) has no toggle at all to seed — there is no client script there — socharts_as_tablesonly ever has an effect onanofox_serve_dashboards's own dashboard pages and the authoring builder (anofox_serve/serve <db>,--app-charts-as-tables).folders—true: the*.sqlfiles one level down are served too, each folder a group of the nav and the/list (unless the file sets its own-- @group) (#772). Notassets/,tasks/,data/or a hidden folder. Off by default, so anarchive/folder already sitting next to the dashboards doesn't go live with an upgrade. A dashboard's id stays its file name (or its-- @id), so two files with one id across folders stop the start.dashboard --check <folder> --options <file>and--siteread the same files.home— a dashboard id:/redirects (302) to/d/<home>instead of showing the landing page, when the viewer may read that dashboard (else the landing page). The server refuses to start if no such dashboard exists.
- DNS rebinding. Only requests whose
Hostis a loopback name on the server's port (127.0.0.1,localhost,[::1]) are served; anything else gets421. Behind a reverse proxy that forwards the originalHost(Caddy does by default), list the public name:{"hosts": ["dash.example.com"]}(a name without a port matches any port;"*"disables the check). - Cross-origin
POSTs are refused (CSRF).
Result cache and single-flight. A snapshot never changes, so a panel's
result is a pure function of its request. Results are cached per snapshot (a
refresh starts an empty cache),
keyed by the parsed request — dashboard, panel, the page object, the viewer's claims and the values of the variables the statement can depend on (in a canonical order) — so a different value of one of those is a different entry, and nothing is shared across dashboards or servers. Identical
requests that arrive while one is running wait for it instead of running again
(errors are shared with them, but never cached).
cache_mb(default 64;0turns the cache off — the single-flight stays): least-recently-used entries are evicted beyond it; one result may take at most a quarter of the cache.- Responses carry an
ETag(a random per-server id, the snapshot epoch and a digest of the key). - Panels that read the clock or random numbers (
now(),random()) are cached like any other: their first result is served until the next refresh. Usecache_mb: 0for those. - A cache hit answers faster than a query, so a viewer can tell whether some
other viewer recently requested the same panel and the same values of the
variables it depends on. All viewers can request every value anyway; if
even that matters, use
cache_mb: 0.
Which variables a panel depends on is worked out once per snapshot, from
the server's own SQL and the snapshot's catalog (never from the request):
getvariable('name') with a literal name, ${name} in its -- @requires and
its tab's, and — through the setup statements before it — what those read:
SET VARIABLE sel = coalesce(getvariable('series'), …) makes every reader of
sel depend on series, and any other setup statement (a TEMP view or
macro can hide a read) adds what it reads to every statement after it. A
macro or view of the snapshot that reads variables counts where a statement
uses it. Whatever the analysis can't see through makes the statement depend
on every variable, as before: a getvariable whose argument is not a plain
string literal, duckdb_variables(), query(), query_table(),
json_execute_serialized_sql(), a string literal that mentions getvariable
or duckdb_variables, or names such a macro or view, a SET / RESET VARIABLE in another form. Variable names are case-insensitive, as in
DuckDB; of two spellings in one request the later wins. A variable a panel
doesn't depend on is not set for it either — the server executes exactly
what the key records, so a value a viewer chose for a variable this panel
doesn't read can never fail its SET or affect its answer. The page gets
the same analysis (window.__served.deps) and, when a viewer changes a
variable, re-requests only the panels that depend on it. To keep clicks
cheap, read selection variables in panels or in a SET VARIABLE, not in a
setup view: a view that reads series makes every statement after it depend
on series.
window.__served.deps (and the X-Anofox-Deps header) tell the page only
names — which request variables a statement can depend on — never SQL or
values. Under a policy that is new information: a catalog view's or macro's
name is otherwise hidden from the page (duckdb_views() is refused), so its
variable names (which could include a __claim_<attr> name) now reach the
page through deps. The values themselves are never exposed, and depsTag
is a non-secret hash.
Superseded requests. A viewer who pages or scrolls a ::PAGED table quickly
would otherwise leave a query running per step. The client sends
X-Anofox-Supersede: <viewer>/<panel>/<kind> (the viewer id is 128 random bits
generated by the page) and aborts its own previous request of that panel + kind;
the server cancels the older request with the same header value (409) and
interrupts its query (duckdb_interrupt) — unless another viewer is waiting for
the same query, which then keeps running for them. A newer identical request
(an impatient double click) takes the running query over instead of restarting
it. Other viewers can't cancel a request without its viewer id. A malformed
header is 400.
- The injected page config is script-safe JSON (
<is emitted as<), titles and ids are HTML-escaped.
Try it: examples/served/ serves two dashboards of
a made-up bakery chain with the result cache, interval and on-demand refresh,
and a data folder of forecast runs picked by a run variable, and has a smoke
test for all of it (node examples/served/smoke.mjs).
SELECT anofox_serve_dashboards('dashboards', 8095,
'{"max_rows": 50000, "timeout_ms": 10000, "threads": 8, "cache_mb": 256,
"refresh_s": 300}');
SELECT anofox_serve_refresh(8095); -- fresh data now, without a restart
SELECT anofox_serve_reload(8095); -- the dashboards folder again (#772, deployment.md §5a)
SELECT anofox_serve_stop(8095);SELECT anofox_serve_dashboards('dashboards', 8095,
'{"css_file": "/etc/anofox/site.css",
"app": {"name": "Acme Analytics", "favicon": "data:image/png;base64,…"}}');-
css_fileis read once at start, served at/static/site.cssand linked last in<head>of every page (the landing page and each dashboard), so its rules win over the theme at equal specificity. The theme's colour tokens (--ax-*) can be overridden there too. Changing the file takes a restart. -
Nothing off the server: the server refuses to start when the file has
@import, aurl(…)that isn't adata:URL, orimage-set(…)/src(…). CSS escapes are decoded before the check. The page's CSP alone would let a stylesheet load images from anyhttps:origin, which would call a third party on every page view. Fonts and images go in asdata:URLs. At most 256 KiB. -
/static/site.cssanswers without a login, like the UI's own files (an embedded page's<link>can't send its session header). It holds no data. -
::CLASSon a panel names one of the stylesheet's classes; the page adds it asax-c-<name>:SELECT sum(amount)::MONEY, 'Revenue'::LABEL, 'kpi-hero'::CLASS FROM sales; SELECT region::XAXIS, sum(amount)::BARCHART, CASE WHEN sum(amount) < 0 THEN 'alert' END::CLASS FROM sales GROUP BY ALL;
.ax-c-kpi-hero { font-size: 1.3em; border-left: 4px solid var(--ax-accent); } .ax-c-alert { outline: 2px solid #b91c1c; }
A name is 1–40 characters of
a-z,0-9and-. Several names are separated by spaces (at most 4). Anything else is ignored, anddashboard --checkwarns about a literal one (class/name). The prefix is the security property: a dashboard author can only reach the operator's classes, never the app's own (to hide a notice or fake a dialog). There is no per-dashboard CSS. -
css_fileis a server option only:dashboard --siteignores it, andserve --dashboards(the CLI's static render) doesn't take it.
The per-viewer state store (options.state), the write-back change log
(options.writeback), the saved views (options.views, #913) and the notes
(options.notes, #889) are files on the node. With durability, the writer
copies them to S3 and a new node starts from there:
INSTALL httpfs; LOAD httpfs;
CREATE SECRET (TYPE s3, PROVIDER credential_chain, REGION 'eu-central-1');
SELECT anofox_serve_dashboards('dashboards', 8095, '{
…, "state": {…}, "writeback": {…},
"durability": {"run": true, "location": "s3://acme-anofox/prod", "snapshot_every_s": 300}}');- Snapshots: every
snapshot_every_s(default 300) and once at the stop, the writer copies each file under its own lock (no write runs meanwhile) and uploads it to<location>/state.jsonl,<location>/writeback.jsonl,<location>/views.jsonland<location>/notes.jsonl, byte for byte, through DuckDB (COPY … TO), so the S3 secret the operator created in the serving session applies. An unchanged file is not uploaded again.locationmay also begs://,r2://or a local directory (an NFS mount, a test). - Restore: at start, a file that is missing locally (a new node) is
restored from its snapshot,
0600. A local file always wins, so a restore never overwrites newer rows. No snapshot yet means an empty start. - One writer: only the replica with
"run": truetakes submissions and saves and keeps the snapshots. The others answer503withRetry-Afterto/api/submitand/api/save, so route writes to the writer (the same replica astasks.runandingest.run). There is no lease: two replicas withrunwould overwrite each other's snapshots. /healthz(for a full login) reportsdurability:writer,last_ok(Unix seconds) andfailing(failed snapshots in a row); every failure is also on stderr.- Personal data: the snapshots hold who answered what. Bucket
encryption, access and retention are the operator's. An erasure
(
erase_user) reaches the next snapshot, but older object versions stay until the bucket's retention removes them.
A tool or an agent can show someone a dashboard without adding a file to the reviewed folder:
SELECT anofox_serve_dashboards('dashboards', 8095, '{
"auth": [{"mode": "oidc", …}, {"mode": "api_keys", "file": "/etc/anofox/keys.json"}],
"preview": {"dir": "/var/lib/anofox/previews", "ttl_s": 86400}}');serve api-key new --file /etc/anofox/keys.json --user svc-agent \
--claim region=EU --dashboards '' --scopes preview
curl -X POST https://dash.example.com/api/dashboards -H "Authorization: Bearer $KEY" \
-H 'Content-Type: application/json' \
-d '{"sql": "SELECT region::XAXIS, sum(amount)::BARCHART FROM sales GROUP BY 1;", "ttl_s": 3600}'
# 201 {"id":"preview-3f9c…","url":"/p/preview-3f9c…","expires":1793000000}- Who may create one: an API key with the
previewscope (API keys → Scopes). The preview runs as that key: every panel gets the key's claims (__claim_*) and goes through the access policy like any viewer's. A key withregion=EUmakes previews that show EU rows only, whoever opens them. - Who may open one:
/p/<id>needs a login, like/d/<id>. A credential limited to some dashboards (an embed link, an API key with adashboardslist) can't open it. The id is 128 random bits; the page is sent withReferrer-Policy: same-origin. Previews never appear in the/list or the nav, and/d/<preview id>is a404. - Checks before it is stored: the same as a dashboard file at start
(one statement each, the data folder's read-only rule), the access
policy's rewrite, and then every panel is run once as the key. A
panel that fails is a
400that lists the failures, and nothing is stored. The design checks ofdashboard --check --strictneed your data and the CLI: run them in the pipeline that builds the SQL (or with the check-dashboards action). - What a preview can't do:
::SAVE,::SUBMIT,-- @load, or read the write-back tables. Reports, alerts and tasks never name one. - Limits:
ttl_s(default 24 h; a request may ask for any value up tomax_ttl_s, default 7 days),max_per_keylive previews (20, then409),max_sql_bytes(256 KiB), and 30 creations per minute per key.DELETE /api/dashboards/<id>with the same key removes one. - Storage: in memory, plus one
0600file per preview indir(which must not be writable by group or others), so a restart and replicas sharing the volume keep them. Expired ones are dropped. Creations and refusals are in the audit log ("audit": "preview").
Scripts, webhooks and other services can push rows into the server:
ATTACH '/data/inbox.duckdb' AS inbox; -- read-write: the rows go here
SELECT anofox_serve_dashboards('dashboards', 8095, '{
"auth": {"mode": "api_keys", "file": "/etc/anofox/keys.json"}, "policy": "none",
"ingest": {"run": true, "database": "inbox", "refresh": true}}');serve api-key new --file /etc/anofox/keys.json --user svc-collector \
--dashboards '' --scopes ingest:events
curl -X POST https://dash.example.com/api/data/events \
-H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
-d '[{"kind": "click", "n": 1}, {"kind": "view", "n": 3, "city": "Bonn"}]'
# {"table":"events","rows":2,"created":false,"added_columns":["city"]}-
Who may write: only an API key whose
scopesname the table (ingest:events, API keys → Scopes). Logins, embed links, share links and keys without that scope get403.options.ingestneedsapi_keysinauth. -
Where the rows go:
<database>.main.<table>ofoptions.ingest.database, attached read-write by the operator (the server refuses to start when it is missing orREAD_ONLY). Never into the snapshot: the rows show after the next refresh.refresh: trueasks for one after each write, at most every 30 s. -
Schema: the first batch creates the table with the types DuckDB infers (strings that look like dates become
DATE), plus_id(a UUID) and_ts(the server time). A table that already exists gets_idand_tsadded. A later batch with a new key adds a column. A key that isnullin every row of a batch adds nothing yet. A value that doesn't fit its column's type is a400that names the column, and nothing is written. A whole number may go into any number column, and aDATEinto aTIMESTAMP; anything else must match. For exact types, give the table a fixed schema, and then any other key is a400:"ingest": {"run": true, "database": "inbox", "tables": {"metrics": {"name": "VARCHAR", "v": "DOUBLE"}}}
-
Body: a JSON object or an array of objects. Keys are plain names (letters, digits,
_), not_id/_ts. Limits:max_body_bytes(default 1 MiB),max_rows(10 000) andrate_per_minuteper key (60, then429withRetry-After). The JSON never becomes SQL text: the server writes it to a private temp file thatread_jsonreads, inside one transaction that is rolled back on any error. -
One writer: only the replica with
"run": truewrites; the others answer503, so route/api/data/to it (the same replica astasks.run, if you use tasks: its database must then be intasks.write). -
Every write and refusal is in the audit log (
"audit": "ingest"), with the key id and the table.
Other systems (a report job, a notebook, a script with an API key) can pull a dashboard without a browser:
curl -H "Authorization: Bearer $KEY" -o sales.svg \
"https://dash.example.com/api/export/sales.svg?v.region=EU&tab=Overview"
curl -H "Authorization: Bearer $KEY" -o totals.csv \
"https://dash.example.com/api/export/sales/totals.csv?v.region=EU"| Request | Answer |
|---|---|
GET /api/export/<dashboard>.svg |
The whole dashboard as one SVG, as dashboard --svg draws it; ?tab=<label> only that tab, ?width=480…4000 (default 1200), ?dark=1 the dark variant |
GET /api/export/<dashboard>.png / .pdf |
The same picture as a PNG (?scale=1…4, default 2; at most 40 million pixels) or a one-page vector PDF, drawn with the bundled Hanken Grotesk font (the default theme's; SIL Open Font License), and a subset of DejaVu Sans for Greek, arrows, math and symbols like ▲ ▼ ✓ ⚠ (its licence: duckext/fonts/DejaVu-LICENSE.txt), whatever fonts the server has. The ⓘ of an ::INFO title is left out (its definition is a hover). Only data: images are drawn, nothing is fetched |
GET /api/export/<dashboard>/<name>.csv / .json |
The rows of the panel named -- @name <name>: CSV with a header row, or a JSON array of objects. Only the data: a column that is only a chart option (::COLORS, ::FLIP, ::YFORMAT, ::HEIGHT, …) or the panel's text (::TITLE, ::SUBTITLE, ::INFO, ::ALT, ::CLASS) is left out. Headers are the query's column names, else the role (category, link) |
GET /api/export/<dashboard>/<name>.svg / .png |
That panel drawn alone, for a chat card or a report (#815): the full width (?width=320…4000, default 640; its ::COL is ignored), its own ::HEIGHT and the other directives right before it, no dashboard title; ?scale= and ?dark=1 as above, ?tab= is 400 |
?v.<name>=<value>sets a variable, as a page URL does (a text value;-- @varsand a credential's locked variables apply). Inputs not given take their default, as on the page. Any other parameter is400.- Every panel runs through the same path as the page's own requests
(
POST /api/panel): the login, the credential's scope (403for another dashboard), the claims, the access policy, the cache, the query slots and the limits. At most 200 panels per export, and 4 ×timeout_msin all. - Answers are downloads (
Content-Disposition: attachment,no-store); an SVG is sent withdefault-src 'none'; sandbox, so opened directly it runs nothing. A CSV cell a spreadsheet would read as a formula (=,+,-,@first) gets a leading', as in the browser's own CSV download. - Setup statements run per panel as always; a
-- @requiresinput that is missing shows its panel as not available.
Viewers can ask the dashboard in plain language ("which region dropped
most?"). A model answers on the server, from the panels this viewer may
already read, and cites the panels and values it used. The client never sends
SQL, and the model never writes any: its only tools read a panel (get_panel),
list the panels and give the answer.
Off by default, at three levels:
- The server:
options.ask, with a login (auth) required. - The dashboard:
-- @ask onin its header, together with-- @vars(a bare-- @varswhen it has no inputs). - The panel:
-- @ask skipkeeps one panel out entirely.
SELECT anofox_serve_dashboards('dashboards', 8095, '{
"auth": {"mode": "oidc", …},
"ask": {"enabled": true, "model": "claude-sonnet-5",
"per_viewer": {"per_hour": 10, "per_day": 30},
"allow": ["group:analysts"]}}');ask. |
Default | |
|---|---|---|
enabled |
false |
|
model |
claude-sonnet-5 |
claude-sonnet-5, claude-opus-5-5 or claude-haiku-4-5 (#846: cheaper; it runs without thinking and effort, which it doesn't take — measure it with scripts/ask-eval.mjs --model claude-haiku-4-5 before you use it); with transport: "openai" the endpoint's own model id (required) |
transport |
anthropic |
or openai (#846): an OpenAI-compatible /chat/completions endpoint at base_url (required), e.g. a self-hosted model; the same tools, checks and limits, no prompt caching or thinking |
key_env / key_file |
ANTHROPIC_API_KEY |
the model key; a key file must be 0600 and not a symlink. With transport: "openai": OPENAI_API_KEY, and optional (sent as Authorization: Bearer; ANTHROPIC_API_KEY is never sent there) |
base_url |
https://api.anthropic.com |
or a company gateway; https:// (http:// only to loopback); no redirects, no proxy from the environment |
provider_label |
Anthropic (Claude) |
named in the viewer notice |
per_viewer |
10 / hour, 30 / day, 200 000 / 600 000 tokens | per user |
tokens_per_hour |
2 000 000 | the whole server |
per_question_tokens |
60 000 | checked before each model call |
max_question_chars |
2 000 | |
concurrency |
4 | questions at once; each runs on a thread of its own, never on the HTTP workers |
allow |
everyone signed in | group:<name>, claim:<name>=<value> |
anonymous |
false |
Ask without a login: anyone who reaches the server spends the key (warned at start) |
mask |
"auto" |
"auto", "off" or a list of column names |
log_questions / log_answers |
false |
question / answer text in the request log |
embed |
false |
Ask inside signed embed links (only about the linked dashboard) |
max_tokens, effort, timeout_seconds |
8 000, medium, 60 |
fixed by the operator |
Who may ask:
- A viewer signed in through the auth proxy, JWT or OIDC, whose credential's scope includes the dashboard.
- An embed session, only with
ask.embedand only about the dashboard its link names. - API keys are refused (
403), and so are shared links (/share/…), because one link serves anyone.
What reaches the model provider:
- The dashboard's text: titles, column names and roles, never SQL.
- The view state: the open tab and the inputs.
- The question.
- The rows of the panels the model reads, as this viewer sees them.
Each panel read goes through the same path as POST /api/panel, with the asking viewer's claims and scope: policies, claims, -- @vars, -- @requires, the caps, the cache and the query slots all apply. The model may set only a variable an input binds, and only to one of that input's options. Ask holds at most half the query slots, so viewers always have slots.
Caps per question:
- 200 rows / 16 KB per panel and 64 KB in all;
- 8 panel reads and 6 model calls;
- one deadline (the panel's own query time ends by it too).
Nothing about the viewer (name, e-mail, claims) is sent. With mask: "auto", values that look like e-mail addresses, phone numbers or IBANs, and columns whose names suggest personal data (name, customer, Kunde, Mitarbeiter, …), go as pseudonyms (⟦P4⟧) and come back as the real values in the answer. This is best-effort minimisation, not a guarantee: use -- @ask skip for a panel whose rows must not leave. dashboard --check flags such columns (ask/personal-column) and unaggregated tables (ask/raw-detail).
POST /api/ask:
- Request body:
{"dashboard", "question", "conversation"?, "tab"?, "vars"?, "panel"?}. Anything else is400; in particular, there is no history field. - The same login, same-origin and
Hostrules as/api/panelapply. - The answer streams as server-sent events:
progress({"phase": "thinking"|"reading", …}), thenanswer:{conversation, text, scope, citations, panels, refreshed}.scopeisanswered,partly,not_on_dashboard,limitorerror. - A citation is
verifiedonly when the server finds that row, column and value in a panel read for this question. - Over a limit, the answer is
429with a plain message. DELETE /api/askcancels the viewer's running question.- Conversations stay on the server, in memory: per user and session, at most 10 turns and 30 minutes. A data refresh starts them over. They are per replica.
Logs:
- One request-log line per question: user, dashboard, conversation, panels read, tool variables by name, outcome, model, request ids, tokens, ms. There is no question or answer text unless
log_questions/log_answersis set, and never panel data. - A viewer's first question in a session writes one
audit: "ask"event.
GDPR, for the operator:
- The operator who turns Ask on is the controller, and the model provider is a processor. A data processing agreement with the provider, a legal basis and an entry in the records of processing are needed before Ask runs on personal data.
- Check the provider's current terms, transfer mechanism and retention, and note the date you checked.
- The people whose data is in the panels are owed Art. 13 / 14 information.
- A DPIA may be needed.
- For employee data in Germany, logging question text per user (
log_questions) can need the works council. - Answers are labelled as AI-generated.
| Threat | Mitigation |
|---|---|
| The model key reaches a browser or a log | It is read only on the server (environment or key file) and is never in a response, a page, an error or a log line. |
| A viewer gets more through Ask than through the page | Every read is /api/panel with the viewer's own claims and scope. Variables only through inputs and their options; @ask skip panels are not even listed. Tested with canary rows under a policy and a claim-dependent text (duckext/scripts/test-ask.sh). |
| SQL from the client or the model | Neither exists. |
| A forged conversation history | The history is held on the server, bound to the session and the claims. |
| Prompt injection through data | No tool has a side effect. Panel data is labelled as data. The answer is plain text, rendered without links or images; navigation happens only through citation chips the viewer clicks. |
| One viewer's data in another's answer | Per-user conversations; the cached prompt prefix is the dashboard's text only (byte-identical across viewers, tested). |
| Spending the operator's key | Login required; per-viewer and server budgets; one question per viewer at a time; ask.allow; API keys and shared links refused. |
| Personal data to the provider | Panels on demand, the caps, @ask skip, masking, no viewer identity; the notice tells the viewer. |
A dashboard published as an agent answers the questions it declares with
-- @question (see DOCS.md) and nothing else, without a model
(plan §10, first slice).
{
"auth": { "mode": "jwt", "...": "..." },
"policy": "/etc/anofox/policy.json",
"agent": {
"dashboard": "suppliers",
"max_rows": 50,
"bundle": "/srv/agent/suppliers",
"digest": "sha256:…"
}
}-
The bundle (#194 A4, plan §7).
dashboard --publish suppliers.sql --out /srv/agent/supplierswrites it:agent.json,mcp-tools.json,capabilities.md,questions.jsonl, a copy ofsuppliers.sqland, with--mapping views.sql --contract contract.sql, the mapping the agent is deployed with (mapping/). It prints the bundle's digest; the deployment config pins it asagent.digest(the bundle holds no copy of it). At the start the server refuses a bundle- whose dashboard isn't the served one, byte for byte;
- with a generated file that differs from the one it rebuilds from the
.sql(a hand-editedagent.json); - with a mapping other than
agent.mapping's files; - with a
policy.json, or any other file--publishdoesn't write (plain files only, no symlinks); - whose digest isn't the pinned one.
A reload that serves another dashboard text, and a snapshot build that reads changed mapping files, are refused too (
503, the old snapshot stays) until a new bundle is published, pinned and started. -
The drift test (
agent.drift, #194 A4b, plan §7):"drift": { "principal": {"user": "drift-job", "claims": {"region": "north"}}, "ranges": "/var/lib/anofox/suppliers-ranges.json" }
After every snapshot build (the start, each refresh, so nightly with
refresh, and each reload) every declared question's panel runs once through the panel path, asprincipal(claims from the server config, under the policy and every limit, never without claims or a bypass), with every input at its default. Only aggregates are kept: the row count, the column names, NULL counts and the numeric columns' min / max. They are compared with the release ranges inranges, a file of the deployment (outside the bundle). A question is switched off on a panel error (a missing column), a changed column set, an empty result that wasn't empty at release, a row count off by more than 10× either way, a numeric column beyond its recorded width or 10× its magnitude, or no record. A switched-off question is refused like an undeclared one (404, not listed, no MCP tool), the same for every caller, and the log names its id and the check (drift/range,drift/empty, …), never a value. The other questions keep answering. While a run is due, agent answers wait (503). Anyone who can shape the source data can switch a question off; that is intended (fail safe)."record": truewritesrangesfrom the start's probes instead (the release step; refused when the file exists, written0600); without it a missingrangesfile refuses the start, and an unreadable one switches every question off.max_rows(default 5000, at most 9999) bounds each probe. -
The policy is configured explicitly:
options.policy, a file outside the bundle, or"policy": "none". Apolicy.jsonnext to the dashboards isn't picked up in agent mode. -
Outbound. The start message lists every destination the server may call (the login provider's keys, a Quack source, snapshots to object storage, report channels; hosts only). Extension telemetry must be off.
-
Routes. Only
GET /api/agent(the questions and their slots, the same for every caller),POST /api/agent/answerand/healthzare served, plus/metricsbehind its own token. Every other path, including the UI, its assets and/api/panel, answers 404. -
An answer.
{"question_id": "…", "slots": {"supplier": "bore"}, "offset": 0, "limit": 20}. Each slot value must match one of its input's options as this caller sees them: exact, then case-insensitive prefix, then contains. More than one match getsclarify.candidatesinstead of an answer. The other inputs take their defaults; the declaring panel runs with exactly those variables through the panel path, under the caller's claims and the policy. Nothing else in the body is accepted (novars,page,filter,sort, …), andlimitis capped atmax_rows(default 50, at most 200). The reply holdsfacts(columns and rows, labelled as data,truncatedwhen more rows follow) and afooter. -
Errors are a fixed message, a code and an error id; DuckDB's text never reaches the caller, and the log line carries only the code, the id and the panel path's status. The panel path's own log lines (a failing panel under a policy, a failing setup statement) leave DuckDB's text out for agent and MCP answers too, since it can quote a slot value.
-
After a refresh or reload, a dashboard version that no longer passes the publish checks is refused on every agent route (
503) until it does again. -
The start is refused without
auth, withauthmodeoidc(it signs people in through browser pages, which agent mode doesn't serve; usejwtwith the same issuer for bearer tokens), withaskon (an agent answers without a model), withlog_vars: "values", unless extension telemetry is off (DATAZOO_DISABLE_TELEMETRY=1), and when the dashboard failsdashboard --check --agent's static checks (question/*,agent/*). -
Without a policy (
"policy": "none") the agent's dashboard still goes through the classifier on every snapshot (#982): no name qualified with another database (a two-part name only for a schema of the default database), the reviewed function list, no macros, noquery/query_table, setup statements only asCREATE TEMP … AS/SET VARIABLE. A dashboard that fails it doesn't start; a refresh or reload with one keeps the snapshot it had. Under a policy the policy's rewrite does the same. -
The operator's own policy is the data boundary, as for
/api/panel; a customer mapping (below) limits the data to the contract's tables.
"agent": {
"dashboard": "suppliers",
"mcp": { "resource": "https://agent.example.com/mcp" }
}adds an MCP server (Streamable HTTP, JSON responses, no session) at
POST /mcp:
- Tools. One per
-- @question, exactly themcp-tools.jsonthatdashboard --publishwrites: the name is the question's id, the description the fixed template "Answers: ? Returns: .", the input schema the question's slots.tools/callis/api/agent/answer: the same resolution, server-fixed variables, row cap and fixed errors; the result isstructuredContent(and the same JSON as text), labelled as data. No model, no other method (resources,prompts, sampling) and no SSE stream:GET /mcpanswers 405. - Resource URL. Its path is exactly
/mcp; a proxy that publishes the server under a prefix strips it before forwarding. - Auth. The bearer is checked like any other request. With
jwt, the start is refused unlessauth.audienceis exactly the resource URL — so a token minted for another API of the same identity provider is refused — andauth.requirepins the tenant, e.g."require": {"tid": "<tenant id>"}— a claim value, or a list of accepted values, checked after the signature. An unauthenticated/mcpcall gets401withWWW-Authenticate: Bearer resource_metadata="…", and the RFC 9728 metadata (/.well-known/oauth-protected-resource/mcp, public) names the issuer. The bearer is never forwarded anywhere. - Connecting a client, e.g. Claude Code:
claude mcp add --transport http suppliers https://agent.example.com/mcp --header "Authorization: Bearer <token>".
A dashboard served to many customers reads a contract
(canonical/<id>.sql: CREATE TABLE statements; NOT NULL for required
columns, a -- @optional comment for optional ones, -- @scope <name> for
a row-policy column, PRIMARY KEY / REFERENCES for the key checks; a
marker comment at the end of a column's line, or on its own line above
it). Each
customer maps its own data onto it in customer-mapping/<customer>/views.sql:
only CREATE [OR REPLACE] VIEW <contract table> AS <query>, one per
contract table, each reading only source.<table> — no macros, no
query / query_table, no table functions but range /
generate_series / unnest, no getvariable, no other database, no
helper view. A scope column the mapping fills with one value on purpose is
marked -- @scope <name> constant in the mapping.
dashboard --conform canonical/supplier-reliability.sql \
--views customer-mapping/acme/views.sql --db acme.duckdb \
[--dashboard supplier-reliability.sql] [--policy policy.json] [--scope region=north,south] \
[--memory-limit 4GB] [--timeout-s 120] [--json]The views are built in a fresh DuckDB that has only --db (a DuckDB file;
attached with extension autoloading already off) attached read-only as
source, external access off and its configuration locked —
never in a session holding anything else. It is a temporary database file
under TMPDIR in an owner-only directory (removed afterwards, on
Ctrl-C / SIGTERM too; the dashboard's TEMP objects go to a schema of their
own there, which shadows the views as TEMP objects do), capped at --memory-limit (default
4GB, 4 threads) set before the lock; each check is stopped after
--timeout-s (default 120) and reported as conform/error (exit 1, as
is any check that fails to run). --scope name= with no values is a usage
error. The report (text, or --json;
exit 1 when the mapping doesn't conform):
- every statement through the mapping classifier (
mapping/refused), every contract table and column present with a compatible type,NOT NULLcolumns without NULLs,PRIMARY KEY/UNIQUEkeys unique,CHECKs holding and references resolving; - each scope column read from a
sourcecolumn (the view's syntax tree is checked:'acme' AS regionis refused unless marked constant), its values within--scope name=a,b, and more than one value when the list has more than one; - the optional columns the mapping leaves out;
- with
--policy: the access policy names only the contract's tables and columns, and its row filters bind against this customer's views (conform/policy) — a policy is written against the contract, never a source; - with
--dashboard: which-- @questions this customer can answer — each question's panel is bound against the views; one that reads a missing optional column is off, with the reason.
At an agent's start (options.agent.mapping, #194 A3b) the server
builds the same views itself, so a customer's agent serves the contract's
tables built from that customer's database:
{"auth": {…}, "agent": {"dashboard": "supplier-reliability",
"mapping": {"contract": "canonical/supplier-reliability.sql",
"views": "customer-mapping/acme/views.sql",
"db": "/data/acme.duckdb",
"scope": {"region": ["north", "south"]},
"memory_limit": "4GB", "timeout_s": 600},
"bundle": "/srv/agent/supplier-reliability",
"digest": "sha256:…"}}The bundle then holds that mapping's views and contract (dashboard --publish … --mapping customer-mapping/acme/views.sql --contract canonical/supplier-reliability.sql), and only that one (plan §5: never
every mapping it was tested against).
Every snapshot build (the start, each refresh) opens a throwaway DuckDB
in the server process — never the serving session: db attached
READ_ONLY as source, the output file (canonical.duckdb in the
snapshot directory) attached, then memory_limit (default 4GB) and 4
threads, external access off, no extension autoloading and the
configuration locked, before any of the mapping's SQL runs. The checks
are dashboard --conform's own (scope is its --scope); a mapping
that doesn't conform stops the start with the same report, and a refresh
with one keeps the snapshot it had. Then each contract table is copied
into canonical.duckdb, which the snapshot attaches read-only as
canonical and makes the default database: the dashboard's bare names
resolve to the contract's tables, and neither the source's own tables nor
anything of the host session (its databases are not copied, attach is
ignored, search_path is refused) is in the snapshot — the dashboard may read only the contract's tables (its
own TEMP objects and CTEs aside; agent/non-canonical-read stops the
start), and a -- @schema <id> header must name this contract. The
agent's questions are bound against the views there too
(like --conform --dashboard): one whose panel reads a column the mapping
leaves out is off for this customer — not in GET /api/agent or
tools/list, refused when asked — and the start log says why. A watchdog interrupts the build after timeout_s (default
600) or when the server stops. mapping can't be combined with
options.source. Don't attach db in the host session as well: the
mapping is meant to be the only way the agent sees it.
SQL that runs on a schedule next to the dashboards, e.g. to load the inbox into a staging database, and then refreshes the snapshot (plan §1):
-- <dashboards dir>/tasks/load.task.sql
SELECT INTERVAL '1 hour' ::SCHEDULE; -- or a TIMESTAMP (the next run), or 'init'
CREATE OR REPLACE TABLE stage.downloads AS SELECT * FROM read_parquet('/data/inbox/*.parquet');
SELECT 1 ::REFRESH; -- rebuild the snapshot after a successful run{"tasks": {"run": true, "write": ["stage"], "timeout_s": 900, "log": "/var/log/anofox/tasks.jsonl"}}- Tasks are files in
tasks/next to the dashboards: author code, reviewed like the dashboards. No request can start, change or see one. - They run on the serving session's own connection, one after another, never
in the locked snapshot. With
::REFRESH, the snapshot is rebuilt after a successful run. - Where they can write (
write): only the databases listed. The task runner starts only when every other database of the session is attachedREAD_ONLY, so DuckDB itself refuses any other write, whatever the task's SQL. Note that the DuckDB CLI's-readonlymakes every laterATTACHread-only too. - Refused in a task:
SET,RESET,PRAGMA,USE,ATTACH,DETACH,INSTALL,LOAD,EXPORT,IMPORT,CHECKPOINT,VACUUM,CREATE TEMP …,CREATE SECRET,COPY … TO. These would change the server's own session or write a file. run: trueon one replica only; the others read the task files (a task that doesn't parse stops the start everywhere) but don't run them.- Each run is one JSON line in
log(task,start,ms,ok,error, with paths in the data folder redacted)./metrics(#765) hasanofox_task_last_success_timestamp_seconds,_runs,_failuresand_consecutive_failuresper task. A failed run is tried again at the next tick; one run's time limit istimeout_s(default 900).
The server renders a dashboard (or one tab) on a schedule and sends it by e-mail or to a webhook (plan §2, §4):
{"notify": {"run": true, "link": "https://dash.example.com", "max_per_hour": 60,
"log": "/var/log/anofox/reports.jsonl",
"smtp": {"host": "smtp.example.com", "port": 587, "from": "reports@example.com",
"user_env": "SMTP_USER", "password_env": "SMTP_PASSWORD"},
"webhooks": {"ops": {"url_env": "OPS_HOOK_URL", "secret_env": "OPS_HOOK_SECRET"}}},
"reports": [{"name": "weekly-sales", "dashboard": "sales", "tab": "Overview",
"vars": {"region": "EU"}, "formats": ["png", "pdf", "csv:totals"],
"schedule": "every monday 07:00 Europe/Berlin",
"as": {"user": "report:sales-eu", "groups": ["sales"], "claims": {"region": "EU"}},
"to": [{"email": "sales-eu@example.com"}, {"webhook": "ops"}]}]}- Who it runs as. Every report has one fixed principal (
as), and every panel runs through the export path (#764) as that principal, under the same policy, claims and limits as a viewer's page, limited to the report's own dashboard. The operator attests that every recipient may see what the principal sees; the start message lists each report's principal.report:*users are reserved: no login method (proxy header, JWT, OIDC, embed link, API key) can claim one, and they never submit or save. - What it sends.
png(inline in the e-mail),pdf, andcsv:<panel>/json:<panel>for a-- @named panel. The text is the dashboard's title, its::ASOFline, the time and, withnotify.link, a link to/d/<id>(which needs a login like any other). - When.
scheduleisinit(once, at the start), a readable form (every 15 minutes,every 2 hours,every hour,every day 06:30,every monday 07:00 Europe/Berlin; without a zone, DuckDB'sTimeZone), or SQL (an INTERVAL or a TIMESTAMP). An interval's first run is one interval after the start, so a restart doesn't send again. A schedule that doesn't evaluate stops the start. - Who sends.
notify.run: trueon one replica only; the others check the reports but don't send.SELECT anofox_serve_report(<port>, '<name>')sends one now, from the session that started the server (for testing). No HTTP request can trigger, change or redirect a report. - Run log and metrics. Each run is one JSON line in
notify.log(report,start,ms,ok,sent,manual,error)./metricshasanofox_report_last_success_timestamp_seconds,_runs,_failuresand_consecutive_failuresper report.
Slack and Teams (R3) are two more channels, for reports, alerts and
tasks.on_failure alike:
{"notify": {"slack": {"token_env": "SLACK_BOT_TOKEN"},
"teams": {"sales": {"url_env": "TEAMS_SALES_WORKFLOW_URL"}}},
"reports": [{…, "to": [{"slack": "C0123ABCD"}, {"teams": "sales"}]}]}- Slack: a bot token (
xoxb-…, scopeschat:write,files:write,channels:read/groups:read). Channels are given by id, never by name. Files are uploaded as bytes (files.getUploadURLExternal, the upload,files.completeUploadExternal), never as a URL Slack would fetch, and only to an upload address onslack.com. Before sending,conversations.infois checked: a channel shared with another organisation (Slack Connect) is refused unlessallow_external: true. Text ismrkdwn-escaped (&,<,>), so nothing in it becomes a link, a mention or@channel. - Teams: a Workflows (Power Automate) webhook URL from the environment (its signature is in the URL; never logged). It gets an Adaptive Card with the text, the PNG inline (up to 750 KB, else a note) and an "Open the dashboard" button. Other files go by e-mail only. Text is defused for the card's Markdown (no link can form from it).
Alerts (options.alerts, R2) use the same channels and principals.
An alert fires when a -- @named panel returns rows (the condition is
ordinary, reviewed dashboard SQL, e.g. WHERE qty < safety):
{"notify": {"run": true, "state": "/var/lib/anofox/alert-state.json", "webhooks": {"ops": {…}}},
"alerts": [{"name": "stock-below-safety", "dashboard": "stock", "panel": "below_safety",
"check": "every 15 minutes", "as": {"user": "report:ops"},
"attach": ["csv"], "to": [{"webhook": "ops"}], "repeat_after": "24 hours"}],
"tasks": {"run": true, "write": ["stage"], "on_failure": {"to": [{"webhook": "ops"}]}}}- A message goes out when the rows appear (
FIRING) or change (CHANGED, by a hash of the rows), again afterrepeat_afterwhile it keeps firing, and once when they are gone (RESOLVED). Nothing is sent while nothing changes. - The state is kept in
notify.state(a0600file, replaced atomically), so a restart doesn't send again. A send that fails keeps the old state: the next check tries again. attachadds the rows as CSV or JSON (not onRESOLVED).anofox_serve_report(<port>, '<alert>')checks an alert now./metrics:anofox_alert_firing,anofox_alert_checks,anofox_alert_check_failuresper alert. Each check is a JSON line innotify.log(alert,rows,status,sent,error).tasks.on_failuretells its recipients when a task starts failing (the first failure in a row, with its redacted error) and when it runs again without one (RECOVERED). It is sent from the task replica.
| Threat | Mitigation |
|---|---|
| A viewer gets a report's data or identity | The report: user prefix is refused by every login method; reports run only from the schedule or the owning SQL session. |
| A report shows more than its recipients may see | One least-privilege principal per report, through the viewer's policy path; the operator attests the audience (D4). |
| Credentials leak | SMTP, webhook, Slack and Teams secrets and URLs come only from the environment; they never appear in the options, logs, errors or Debug output. |
| Mail sent in clear, or downgraded | STARTTLS is required (a server without it is an error), or implicit TLS; certificates checked against the Mozilla roots. tls: "none" only to a loopback relay. |
| SSRF / exfiltration | Endpoints are fixed in the configuration, never built from data; https:// only (http:// to loopback), no redirects, no proxy, 30 s timeout. |
| Header or markup injection | Recipients are plain addresses (checked at start) and go only into the envelope (Bcc); the subject has no line breaks (RFC 2047); the HTML is escaped; file names are fixed; CSV formula cells are neutralised as in exports. |
| Spoofed or replayed webhooks | X-Anofox-Signature: sha256=<HMAC-SHA256(secret, "<X-Anofox-Timestamp>.<body>")>; the receiver checks it and the age of the timestamp. |
| Alert storms | One message per change of state (plus repeat_after), never per check; the state survives restarts. |
| Flooding | At most 50 recipients per report, 10 MB of files, and max_per_hour messages (default 60) for all reports together. Over a limit nothing is sent, the run is logged as failed and the metrics show it. |
This is the one write path on a server that is otherwise read-only by
design. A viewer's click on a ::SUBMIT button (see docs/DOCS.md →
"Recording answers") is turned into one JSON Lines record, appended by the
Rust server itself to a file no SQL ever reaches — never a new table, never
a write through COPY/INSERT. The snapshot stays exactly as read-only and
locked-down as everywhere else in this document.
"state": {
"path": "/var/lib/anofox/state.jsonl",
"dashboards": ["tutorial"],
"read": ["my-progress"],
"trainers": {"dashboards": ["progress"], "groups": ["trainers"]},
"text_max_chars": 1000,
"rate": {"per_minute": 6, "burst": 3},
"max_per_viewer": 1000,
"max_mb": 256
}- Storage. One append-only JSON Lines file (
options.state.path), openedO_NOFOLLOWat0600, a single writer enforced withflock(a second server, or this build's owndashboard state export|eraseCLI, on the same path refuses outright rather than risk interleaving writes — "in use by another server"). Each submission iswrite_all+fdatasync'd before the201response, so an acknowledged submission is durable; a crash mid-write leaves a torn final line, truncated and logged at the next start. The path must not sit insideoptions.data, the dashboard folder or the snapshot's temp directory (it would otherwise become reachable throughallowed_directories) — the server refuses to start otherwise.flockis unreliable over NFS/CIFS: keepoptions.state.pathon local storage. - Requires
auth. No anonymous submissions, and neither an API key nor an embed link without its ownuser(a shared identity) can submit — both get403 "submissions need a personal sign-in".statewith anembedlogin also requires an explicitframe_ancestors(clickjacking the button through an iframe). - The endpoint,
POST /api/submit: re-runs the::SUBMITstatement for the viewer (so what the page showed and what the server accepts always agree), then re-runs each recorded input and checks the submitted value is one of its real options — or, for a credential-locked variable (an embed link's own fixedvars, an OIDC/JWT claim mapped onto a variable), records that locked value instead of the viewer's own pick, a locked list exactly like a locked scalar (a credential-locked::MULTISELECTrecords its whole list; fixed in the same PR that added this section). RequiresOriginequal toHost(no "missing Origin passes", unlike a read/api/panel),Sec-Fetch-Site: same-originwhen present, andContent-Type: application/jsonplus a custom header — a cross-site POST gets no CORS preflight granted anywhere on this server, so it never lands. A client nonce (id) makes a retry after a lost response idempotent: the sameidtwice appends once; a different answer always needs a new one (the client's job — this build's browser client only ever reuses a retry id when the vars it is about to send are byte-identical to the failed attempt's). - Limits, all per
options.state.rate/max_per_viewer/max_mb(defaults shown above): a per-user token bucket (429+Retry-After), a global submit rate, a cap on submissions per viewer (409once reached), a store size cap (507, logged once,/healthzreportsstate.full), 16 KiB body, 32 recorded variables, 1000-characterTEXTvalues (options.state.text_max_chars). A validation failure still consumes a rate-limit token (so it can't be used as a free oracle loop); a refusal before that (auth, CSRF) does not. - Reading it back (
viewer_state/viewer_state_latest, schema indocs/DOCS.md): rows are scoped by construction — a connection only ever has the rows it may see inserted into it, never aWHERE __claim_user = …filter sitting on top of everything. A dashboard indashboards/readgets the signed-in viewer's own rows; one intrainers.dashboardsgets every viewer's rows only for a viewer intrainers.groups/trainers.users— anyone else on that same dashboard still gets only their own (fails safe, not refused). The panel/warm-connection cache keys fold in the relevant generation (the viewer's own row count, or the global sequence for a trainer read), so a submission is reflected on the very next read, never served from a cache or a warm connection that predates it. - Logging. The request log (
options.log) gets/api/submitlike any other path, withvarsfollowinglog_varsas usual (valuesduplicates answers into that log — a deliberate, documented trade-off, same as everywhere elselog_vars: valuesis set). The audit log (options.audit, available becausestaterequiresauth) gets asubmitevent,okor a specific deny/error reason, never the values — who submitted what<submit id>, when, not what they answered. - Credential-locked lists are recordable. A locked scalar variable (an
embed link's
vars, say) was always recorded as the locked value, never the viewer's own pick; a locked list (a credential-locked::MULTISELECT) is too — it used to be refused outright with "is not a settable variable on this dashboard", a misleading message for a variable that is settable and is declared, just happened to be a list. If you still see that message for a variable you can confirm is in-- @vars, it means the dashboard's own-- @varsgenuinely doesn't list it — the one case that message still describes correctly. - Retention and erasure are the operator's job — nothing expires
automatically.
dashboard state export|erase(run offline; both refuse while a server still has the file open, the sameflockthe server itself takes —exportand a dry-runerasetake it as a shared lock, so either can run alongside the other, or alongside itself, but not alongside a live server or an appliederase):dashboard state export /var/lib/anofox/state.jsonl --user alice@example.com --format csv --out alice.csv dashboard state erase --user alice@example.com /var/lib/anofox/state.jsonl # dry run dashboard state erase --user alice@example.com /var/lib/anofox/state.jsonl --yes # actually erase
--usermatchesclaims.userexactly and case-sensitively (the same string the server stored it as) — an IdP that sendsAlice@example.comfor one sign-in andalice@example.comfor another produces two distinct subjects as far as this CLI (and the store) are concerned; check the storeduservalues (an unfilteredexport, orread_jsonbelow) before assuming one spelling covers a person. Neither subcommand accepts an empty--user— refused outright, rather than silently matching nothing.exportprints matching records (--userscopes a data-subject request; omit it for a full dump) as the store's own JSON Lines (--format jsonl, default) or as one CSV row per recorded variable (--format csv, the same shapeviewer_statereads back;value/value_listare literal JSON text, lossless even for aMULTISELECT's list);--out FILEwrites a new file instead of stdout — created0600, never through a symlink, and refused outright if it already exists unless--forceis also given. Prefer--outover stdout: without it, the export's personal data lands wherever the shell's own redirection and the process's umask put it, with no0600of its own — wrap it in a subshell that sets a tight umask first, e.g.(umask 077; dashboard state export … > alice.csv), rather than relying on a laterchmod. Bothexportand a dry-runeraseopen the store read-only: neither ever creates the file, truncates a torn tail, tightens loose permissions, or writes a header into an empty file — only an appliederase --yestouches the file on disk. Like a server at start-up, a runningexportorerase(dry run or applied) takes the store'sflock, so a server start while one is running gets the same "state file '…' is in use by another server" refusal a second server would.eraseis a dry run by default — it only reports how many records would be removed until--yesis given — and writes one audit line per applied attempt (--audit stderr|FILE, defaultstderr; same target syntax asoptions.audit), outcomeok/error, the operator's own numeric uid (getuid()— not$USER, and not the erased viewer'suser), never the values. An applied erase is crash-safe: it writes the kept rows and the original header line, byte for byte, to a fresh temp file in the same directory,fsyncs it, thenrenames it over the original andfsyncs the directory — the original is never modified in place, so a crash at any point before therenameleaves it completely untouched, and from the instant therenamelands the new content is the only content anyone can ever open at that path again. A crash between the write and therenamecan leave a.<store file>.erase-tmp-<pid>-<ns>file next to the store; it holds only the rows that would have been kept, so it's still personal data in its own right and the operator should delete it by hand. The erased user'sseqnumbers are not reserved — after a restart a later submission may reuse one. That's harmless for every guarantee above (no in-memory cache survives a restart to be confused by it, anderaseonly ever runs while the server is stopped) but meansseqis not a permanent forensic id: the audit log, when configured, is the durable record of when something happened. The raw file is also plain JSON Lines for ad hoc batch analysis without this CLI at all —duckdb -c "FROM read_json('state.jsonl')"— offline, same caveat.eraseis a logical delete, not a secure wipe. Therenameonly ever points the directory entry at a new inode holding the kept rows; the old inode's blocks are freed for reuse, never zeroed, so the erased rows can still be recovered from the raw block device until something else overwrites them. On a copy-on-write filesystem (btrfs, ZFS, APFS), in a filesystem snapshot, or in a backup taken before the erase, the old blocks are retained deliberately anderasehas no way to reach them at all. If an erasure request is a GDPR Article 17 matter, treatdashboard state eraseas covering the live store file only, and separately check — and expire — any snapshot or backup retention that could otherwise keep the same rows around indefinitely. - Single replica in v1. One
flock'd file, one writer. Multiple replicas behind a load balancer would need an external store; not planned unless asked for.
Threat model. Assets: learners' answers (A1, confidentiality); the
record's integrity — who submitted what, when (A2); the read-only guarantee
for options.data and the snapshot (A3); trainers' browsers/exports (A4);
server availability and disk (A5); the audit trail (A6).
| Threat | Mitigation |
|---|---|
Submit as someone else (forged user) |
user only from authenticated claims; the request body has no user field at all (unknown fields 400) |
Read another viewer's answers via viewer_state |
Rows are inserted into a connection only when permitted; trainer access needs dashboard and group; cache/warm keys fold in claims + the state generation |
| Read the state file directly from dashboard SQL | enable_external_access = false + lock_configuration; the path is refused inside options.data; the file can't be snapshotted (it is never a DuckDB database) |
| Record a value outside an input's real options | The server re-runs the input as the viewer and checks membership, kind by kind |
| SQL injection through an answer | Values are never spliced into SQL: stored as JSON, read back through bound parameters |
| Store-file injection (a forged record, an embedded newline) | serde_json's single-line encoding; every line is re-validated at the next start, fail closed |
| CSRF (a foreign page submits on the victim's behalf) | Origin required and equal to Host, Sec-Fetch-Site, JSON content type + a custom header (no CORS preflight is ever granted) |
| Clickjacking the submit button | frame-ancestors 'none' by default; state + embed requires an explicit frame_ancestors |
Many people submit under one shared identity (an embed link without user, an API key) |
Refused outright, 403, audited |
| Flood (disk fill, CPU via validation queries) | Per-user and global rate limits, a per-viewer cap, max_mb, body/text caps — validation is usually a cache hit already |
| Double submit / racing the author's "once" gate | A client nonce dedups a retry; a per-viewer mutex makes the gate check and the append atomic |
| Stored XSS / phishing link / formula injection against a trainer | Every cell/markdown value is escaped, links go through safeUrl; every CSV export — the browser's ::DOWNLOAD_CSV / query export (web/app.js, #520/#526) and dashboard state export --format csv (this PR) — neutralises a leading = + - @ or a tab/CR on every string cell (a plain number, including a real negative one, is left alone); the .xlsx writer needs no such prefix, since its string cells carry an explicit inline-string type Excel never re-parses as a formula; a lint warning flags markup built from viewer_state |
| Submit without a login | auth is mandatory wherever state is configured; 401 before anything else runs |
Misconfiguration (state inside data, a shared/world-writable directory, a symlink, two servers on one file) |
Start-time refusals, O_NOFOLLOW, 0600, flock |
| Crash or I/O error loses or tears a record | fdatasync before the 201; a torn tail is truncated and logged at the next start; an I/O error marks the store failed (503 from then on, never a silent retry) |
| Answers leaking into logs | The audit log never carries values; the request log only with log_vars: values (documented, opt-in) |
| Erasure/export rewriting the live file, or a crash tearing it | Both refuse outright while a server holds the file's flock; export/dry-run erase open read-only and never mutate the file; an applied erase writes to a temp file and renames it over the original, so a crash leaves either the untouched original or the complete new file, never a torn mix |
The second write path: a writer saves an edited model — a ::DIAGRAM
graph or a ::FORM's values (::SAVE, see docs/DOCS.md → "Saving
edits") — into tables the server declares. Like options.state, Rust
appends each save to a file no SQL reaches; the snapshot stays read-only.
"writeback": {
"path": "/var/lib/anofox/plan-changes.jsonl",
"dashboards": ["twin"],
"writers": {"groups": ["planners"], "users": ["lead@example.com"]},
"tables": {
"plan_nodes": {"key": ["id"], "columns": {"id": "VARCHAR", "type": "VARCHAR", "label": "VARCHAR", "stage": "INTEGER"}},
"plan_edges": {"key": ["from", "to"], "columns": {"from": "VARCHAR", "to": "VARCHAR"}},
"plan_params": {"key": ["id"], "columns": {"id": "VARCHAR", "lead_time": "DOUBLE"}}
},
"max_rows": 2000,
"text_max_chars": 1000,
"rate": {"per_minute": 12, "burst": 5},
"max_mb": 256
}- What may be written. Only the declared tables, only their declared
columns, each value coerced to its declared type (
VARCHAR,INTEGER,BIGINT,DOUBLE,BOOLEAN,DATE; text capped attext_max_chars), every key column non-null. A graph save replaces both of its tables (nodes:id, type, label, stage— the ones the table declares; edges:from, to), at mostmax_rowsrows, no duplicate keys; a form save upserts one row of a table keyed byid. Never client SQL. - Who.
authis required; the viewer must be a personal sign-in (no API key, no shared embed identity) listed inwritersby user or group, and the dashboard must be indashboardsand in the credential's scope. Everyone else gets the button disabled with the reason, and403from the endpoint. With anembedlogin,frame_ancestorsis required. - The endpoint,
POST /api/save—{"dashboard", "panel", "id", "vars", "graph" | "form" + "key", "base"}: the same CSRF gate as/api/submit(Originrequired and matching,Sec-Fetch-Site: same-origin, JSON,X-Anofox-Submit: 1), a 1 MiB body cap, the per-writer rate limit plus the global 20/s, one save at a time per writer (409+Retry-After: 1), a retry with the sameidwithin 10 minutes answered from memory instead of saved twice. The server re-runs the dashboard's::SAVEstatement with the viewer's variables (it names the tables); a table the config doesn't declare is refused (400, saying which). - Storage. The change log is the
options.statestore design (flock,O_NOFOLLOW,0600,fdatasyncbefore the201, torn-tail recovery, the same path rules, never theoptions.state.path), its header marked"kind":"writeback"so the two files can't be swapped. One line per save:{"seq", "ts", "user", "auth", "dashboard", "submit": <the ::SAVE column>, "id", "vars": {"changes": [{"table", "op": "replace"|"upsert", "rows"}], "base"}}./healthzreportswriteback: {ok, full}; withoptions.auditevery save and refusal is asaveevent. - Reading the saves. Every dashboard whose SQL names a declared table
reads it as a per-connection
TEMPtable built from the change log: after a graph save, exactly the saved rows; otherwise the base table (the one an unqualified name resolves to) cast to the declared types, with the saved rows merged over it by key (a form save changes only the fields it saved). Rows go in through an Appender, never as SQL text. Those dashboards key their cache and warm connections on the change log's generation, so a save re-runs exactly the panels that read it — for every viewer. Start-time refusals: a base table with a column the declaration doesn't name (a saved table would hide it), a saved table the access policy names only in another schema than saved tables live in (ambiguous), more than onesearch_pathentry. - With an access policy (#726, #736). A saved table the policy
names stays a policy table: its per-viewer view reads base ⊕ saved
rows (built per connection under a server name,
__anofox_wb_<t>, never under the table's own), so its row filter and column rules apply to saved rows exactly as to the base's. Saves into it are checked as the writer before they are appended (403, saying why): a column the policy restricts for the writer can't be written; a graph save, which replaces every row, is refused when the table has a row filter; and a form save may only touch rows the writer can see — the row as it is, and as the save leaves it (so no editing, or creating, a row outside your access). The check builds the table as panels see it on a fresh connection with the writer's claims and compares the touched rows counted directly and through the writer's view; if it can't run, the save gets a generic500(details in the log only). A saved table the policy doesn't name is outside it: every viewer of a dashboard that reads it sees all of its rows and columns (the declaration names every column; the start line lists these tables) — a TEMP table the policy's rewrite accepts likeviewer_state. Keep anything per-viewer in tables the policy names. - Permissions kept in a saved table (#1220). A row filter that reads a
saved table the policy names (
"athleten": {"rows": "nummer IN (SELECT nummer FROM nutzer WHERE email = getvariable('__claim_user'))"}) reads that table's base ⊕ saved rows, unfiltered, as row filters read tables: a save tonutzerchanges whatathleten's viewers see at once. Every dashboard reading such a table gets the saved table built on its connections and keys its cache and warm connections on the change log's generation, and a save's own check builds the saved tables the touched table's filter reads as they are now. This makes the saved table part of the access policy: whoever may save to it decides who sees what. Keep it to admins —options.writeback.writers, its::SAVEonly on an admin dashboard, and a row filter on it that shows its rows only to admins (a save may only touch rows the writer can see). - Conflicts (optimistic). A save carries
base, the change log generation its page loaded at (moved on only by that page's own saves). If a newer save would be silently overwritten — any later change to a graph's tables, or a later save of the same form row / a replace of its table — the server answers409{"error": "changed", "gen", "changes": [{user, ts, table, op, keys}]}, the page says who saved what and when, re-runs its panels on theirs, keeps the viewer's edits, and a second Save (now on the newer generation) keeps this one. A different row never clashes. The check and the append run under one short lock (no SQL, no response written while it is held), so two writers can't both pass it. - Audit. With
options.audit, every save is asaveevent:okwithdetailnaming the::SAVE, the record'sseqand its tables, ops and keys (plan_params:upsert(wh),plan_nodes:replace(3)); refusals with their reason (not_writer,conflict,invalid_value,rate_limited,csrf, …). The change log keeps every saved row, so a change's before and after are both on record; undoing one is a new save of the earlier values.
A viewer's Views (named page states: inputs, selections, brushed ranges,
frames, ::VIEW picks, tab) are kept per login on the server instead of in
one browser, so they follow the viewer to another browser or device. A
served page then shows Views in its header: Save this view…, the saved
views (newest first), Delete a view…. Without options.views (and in the
builder or a published site) the browser keeps them (#888).
"views": {"path": "/var/lib/anofox/views.jsonl", "max_per_dashboard": 50, "max_mb": 64}- Who. Needs a login (
options.auth; the start refuses otherwise) and a personal sign-in: an API key, a share link or another reserved identity gets403, and a page holding an embed link's session doesn't offer it. Every read and write is keyed by the signed-in user, and a credential's dashboard scope applies; nobody reads or deletes another viewer's views. - What is stored. A name (1–80 characters, no control characters) and
the address' state only:
tab,v.*,frame.*andview.*parameters (≤ 64, ≤ 4 KB, re-encoded). Never a whole address: the page opens a view on its own dashboard path, so a stored view can't send anyone elsewhere. Av.*name the dashboard doesn't declare is ignored by the page, as one typed into the address bar would be; the name is shown as text. - Endpoints.
GET /api/views?dashboard=<id>→{views: [{id, name, query, at}], max};POST /api/views{dashboard, name, query}→201(the same name replaces that view);POST /api/views/delete{dashboard, id}. Writes pass the same cross-site gate as/api/submit(Originrequired and matching,Sec-Fetch-Sitesame-origin when sent, a JSON body,X-Anofox-Views: 1); a cross-site read is refused too. At mostmax_per_dashboard(default 50, ≤ 500) views per viewer and dashboard (409), 5000 lines per viewer, 30 writes a minute (burst 10). - The file. The state store's format and file discipline (single
writer,
fdatasyncper write, torn-tail recovery, the same path rules), its header marked"kind":"views", so it can't be swapped with a state file or a change log, and its own file (notoptions.state's oroptions.writeback's). One line per save ("submit": "view","vars": {name, query}) or delete ("submit": "delete", the view'sid).options.durabilitykeeps it as<location>/views.jsonl. Requests are in the request log (/api/views…, the user and dashboard, no name or state).
Viewers pin a short note to a chart, at a value or over a range ("promotion", "data error"); everyone who sees the dashboard then sees it on that chart: a dashed rule (a range: a shaded band) in the theme's warning colour, its text, author and day as the tooltip. A writer points at a value (or brushes a range) and picks ✎ Add a note in the chart's tools; a click on a note shows it, with Delete for its author or a moderator.
"notes": {
"path": "/var/lib/anofox/notes.jsonl",
"dashboards": ["sales"],
"writers": {"groups": ["analysts"]},
"moderators": {"users": ["lead@example.com"]},
"max_per_dashboard": 200,
"text_max_chars": 280,
"max_mb": 64
}- Who. Needs a login (the start refuses otherwise) and lists its
dashboards (an unknown one refuses the start). Every credential that may
open a listed dashboard reads its notes (scope applies). Adding one needs
a personal sign-in among
writers(none named: every personal sign-in); an API key, a share link or a reserved identity never writes. A note is deleted by its author or amoderatorsmember. - What is shown to others. The text (1–
text_max_charscharacters, no control characters), the anchor value(s) the writer chose, the author's user id and the day. Nothing is read from the data, so a note shows only what its writer wrote — but it shows it to every viewer of the dashboard, whatever the access policy lets each of them see: name as writers only people who may share what they see with all of them. The renderer escapes the text (an SVG<title>), the page sets it as text. - Endpoints.
GET /api/notes?dashboard=<id>→{notes: [{id, panel, x, x2, text, by, at, mine}]};POST /api/notes{dashboard, panel, x, x2?, text}→201(panelis a statement number of that dashboard);POST /api/notes/delete{dashboard, id}. Writes pass the same cross-site gate as/api/submit(headerX-Anofox-Notes: 1); at mostmax_per_dashboard(default 200, ≤ 2000) notes per dashboard, 20 writes a minute per user (burst 5). - The file. The state store's format and discipline, header
"kind":"notes", its own path. One line per note ("submit": "note","vars": {panel, x, x2?, text}) or delete.options.durabilitykeeps it as<location>/notes.jsonl;dashboard state export|erasework on it.
A map in 'mercator'::PROJECTION with 'on'::MAPTILES draws the
installation's raster tiles under its features. The source is set here,
never in a dashboard; without this option ::MAPTILES draws nothing and
maps stay offline. Review: security/basemap-760-review.md.
Served pages, exports (/api/export) and dashboard --svg --basemap draw
the tiles. A static dashboard --site doesn't yet: it has no server to ask.
"basemap": {
"url": "https://tiles.example.com/{z}/{x}/{y}.png",
"attribution": "© OpenStreetMap contributors",
"max_zoom": 16,
"cache_dir": "/var/cache/anofox/tiles",
"cache_mb": 256,
"upstream_per_minute": 600
}- The source.
urlis anhttps://template, or an absolute directory template (/srv/tiles/{z}/{x}/{y}.png, regular files only, links refused). It holds{z},{x}and{y}once each and no other placeholder. The three numbers of a request are the only input that reaches it.attributionis required and drawn on every tiled map. Check your provider's terms: OpenStreetMap's public tile servers forbid heavy use, so run your own or use a commercial provider. - The browser never contacts the source. The page asks this server,
GET /api/tiles/{z}/{x}/{y}?dashboard=<id>: a login (when configured), a dashboard in the credential's scope that uses::MAPTILES, a tile in the grid up tomax_zoom(default 16, ≤ 19). Same-origin requests only. 600 requests a minute per viewer (burst 200); cache misses are capped atupstream_per_minutefor the whole server, with at most 8 running at once (more get a503). - Upstream. No proxy from the environment, no redirects, 5 s to connect
and 15 s per tile. Only PNG or JPEG bodies up to 512 KB are accepted,
checked by their bytes. They are served with
nosniffandCache-Control: private. A failure is a502, and the reason goes only to the server's stderr. - The cache. An
https://source needscache_dir(orcache_mb: 0for none): a directory this server owns and keeps0700(it is created if missing; a link or a shared directory refuses the start), outside the dashboards folder andoptions.data. Files are namedz-x-yand kept at0600. The oldest files go first once the cache passescache_mb. The cache is shared between viewers: tiles are public map imagery, and its timing can show at most that someone on this server looked at an area. Setcache_mb: 0if that matters.
anofox-scenario keeps
Git-like branches of a database inside its file. With the extension loaded
in the serving session and options.scenarios, every scenario of one
database is attached to the snapshot read-only, and each request gets three
helpers:
"search_path": "warehouse",
"scenarios": {"database": "warehouse", "tables": ["plan", "capacity"], "max_scenarios": 50}SELECT name AS scenario ::SCENARIO FROM anofox_scenarios(); -- the picker: main + every scenario
SELECT week ::XAXIS, sum(qty) AS "Planned" ::BARCHART FROM plan GROUP BY 1; -- reads the picked one
SELECT scenario ::XAXIS, sum(qty) AS "Planned" ::BARCHART
FROM anofox_scenario_rows('plan') GROUP BY 1; -- the table per scenario
SELECT sku ::TABLE, change_type, old_value, new_value
FROM anofox_scenario_diff('demand_up', 'plan'); -- what changed (against := 'main')databasemust be the dashboards' default database (options.search_path's first).tableslists the only tables the helpers read; any other name is an error. At mostmax_scenarios(default 50) scenarios are attached, by id, asscn_<id>.- Read-only. The host is attached read-only, so a write through a
scenario is refused. A dashboard that calls one of anofox-scenario's
write functions (
scenario_create,_drop,_freeze,_unfreeze,_merge,_migrate,_refresh), directly or as SQL text in a string (query('…')), is refused at start whenever the extension is loaded: on a read-only host they still change what the long-lived snapshot reads (anofox-scenario#66). That check is a stopgap until #66 is fixed: SQL text built at run time isn't seen, so don't serve dashboards that runquery()on text a viewer can set while anofox-scenario is loaded. - A database holding scenarios is snapshotted with the extension's
internal schema (the copy allows it for its own duration only), with or
without
options.scenarios. - The picker.
::SCENARIOis a::DROPDOWN; when a request's value is exactly the name of an attached scenario, the server sets that request'ssearch_pathto its catalog (followed byoptions.search_path's further entries), so unqualified names (FROM plan) read the branch and the dashboard's SQL doesn't change.main, no value or any other value read the base. Such a dashboard always gets a fresh connection (no warm reuse), and its-- @materializestatements run per request (no shared result). A statement that names scenarios itself (anofox_scenarios(), the helpers,scenario_*) keeps the base path: anofox-scenario finds its registry through the search path's first catalog. The page gets the picker's name (scenarioVar), so a pick re-runs every panel and a?v.scenario=link opens the same scenario. Withoutoptions.scenariosit's an ordinary dropdown. - Not yet (plan: plan-scenarios.md): combining
options.scenarioswith an access policy, an agent mapping oroptions.preview(a preview key's SQL could build a write call at run time; anofox-scenario#66).
With writers, a writer adds scenarios and saves a ::FORM's row into
one from the page. The server does it on its own connection to the live
database; a request never runs ATTACH, scenario_* or a write as SQL.
"scenarios": {
"database": "warehouse",
"path": "/var/lib/anofox/scenarios.jsonl",
"dashboards": ["sop"],
"writers": {"groups": ["planners"]},
"tables": {
"capacity": {"key": ["line"], "columns": {"line": "VARCHAR", "per_shift": "DOUBLE"}},
"plan": {"key": ["sku", "week"], "columns": {"sku": "VARCHAR", "week": "DATE", "qty": "DOUBLE"}}
},
"mode": "delta",
"rate": {"per_minute": 12, "burst": 5}
}SELECT name AS scenario ::SCENARIO FROM anofox_scenarios();
SELECT 'second_shift' AS new_name ::TEXT;
SELECT 'Add scenario' ::SAVE, 'create' ::SAVE_ACTION, 'new_name' ::SAVE_KEY, 'scenario' ::SAVE_SCENARIO;
SELECT field AS cap ::FORM, type, value, options FROM capacity_fields;
SELECT 'Save capacity' ::SAVE, 'cap' ::SAVE_FORM, 'capacity' ::SAVE_TABLES, 'scenario' ::SAVE_SCENARIO;'create'::SAVE_ACTIONmakes a scenario named by the::SAVE_KEYvariable from the picked one (ormain), inmode(delta, the default, ormaterialized), and the page picks it. Names are letters, digits and_(at most 64; anofox-scenario's rule), nevermain; at mostmax_scenarios. Tables without a primary key get their declared key as anofox-scenario'skey_columns.- A write (
::SAVE_ACTION'write', the default) saves the form's row into the picked scenario: the form's fields (plus the table's single key column from::SAVE_KEY's variable, when the form doesn't carry it), each declared intablesand coerced to its type, upserted by the declared key. An existing row keeps the columns the form doesn't carry. Saves never writemain; a frozen or unknown scenario is refused (409). - Who: a personal sign-in listed in
writers(no API keys, no shared embed identity), on a dashboard indashboards, with the same CSRF gate, body cap, rate limit and retry id as write-back's/api/save. The scenario and the new name come from the request's variables after the dashboard's-- @varsallow-list and credential locks. - How: checked against
scenario_list(), then in one transaction on the live connection (its search path set todatabasefor the operation):scenario_create(?, …)with bound names, orATTACH '<name>' AS __anofox_scn_w_<random> (TYPE scenario)and a boundUPDATE/INSERT; the log line is appended (fdatasync) before the commit, so every committed operation is in the log (a failed append rolls back). Then the snapshot is refreshed (a burst of writes waits for one refresh) and the answer carries itsepoch. - Start checks:
options.authis required (an embed login needsoptions.frame_ancestors);databasemust be attached read-write; every declared table must be in itsmainschema with the declared columns;pathfollowsoptions.state.path's rules and isn't another store's./healthzreports the log asscenarios: {ok, full};options.durabilitykeeps it with the other stores.
approvers ({"groups": […], "users": […]}) may freeze, unfreeze, merge
and drop the picked scenario — a separate right from writers (an
approver needn't be a writer, and a writer can't approve). Either list is
enough to enable the endpoint.
SELECT 'Freeze' ::SAVE, 'freeze' ::SAVE_ACTION, 'scenario' ::SAVE_SCENARIO;
SELECT 'Unfreeze' ::SAVE, 'unfreeze' ::SAVE_ACTION, 'scenario' ::SAVE_SCENARIO;
SELECT 'Make official' ::SAVE, 'merge' ::SAVE_ACTION, 'scenario' ::SAVE_SCENARIO;
SELECT 'Drop' ::SAVE, 'drop' ::SAVE_ACTION, 'scenario' ::SAVE_SCENARIO;- Freeze locks a scenario (writes are refused); unfreeze unlocks it, except one that was merged.
- Merge ("make official") is two steps in the page: the first click
asks for a preview (
"preview": true: rows per table, nothing changes), the second merges. It runsscenario_merge(name, on_conflict := 'abort')after checkingscenario_merge_preview: whenmainchanged a row the scenario changed too, it is refused (409,{"error": "conflicts", "changes": […]}) and nothing is merged — conflicts are never resolved automatically. A merged scenario ends frozen. - Drop deletes the scenario; the page goes back to
main. - A scenario that others branch from can't be merged or dropped (drop those first). Every approval is a log line like a write, in the same transaction rule (log before commit).
The most locked-down option: no client data API at all, server-side SVG only.
Consumers pick a dashboard id and whitelisted params
(-- @param region [EU, US] = EU; a value outside the list is 400).
-
Panels run
duckdb -readonly; after the server-declared-- @loads, each session setsenable_external_access = falseandlock_configuration = true. -
--max-rows(default 100,000),--timeoutseconds (default 30; the CLI is killed),--threads(default 4),--cache <seconds>(shared render cache, doubles as the freshness knob). -
--init setup.sqlruns once, read-write, before serving (attach sources, create views/tables). CLI dot-commands are refused there too. Without--dbthe server uses (and creates) a private empty database; a--dbthat doesn't exist is refused at startup. -
A dashboard's own setup statements run in every page's read-only session, after the locks above (a TEMP VIEW lives in one session, #680) — only
SET VARIABLEandCREATE [OR REPLACE] TEMP VIEW|TABLE … AS <query>, the locked server's data-folder rule, checked with DuckDB's parser at startup. Any other setup statement (and one setting a__claim_*oranofox_datavariable) is skipped with a startup warning: do it in--init. The credential's locked variables and claims are set again after each one. -
-- @requires(DOCS, Not available): checked per request with the request's variables, likedashboard --check; the session can open no file, so every such input counts as missing here — a gated panel shows Not available (naming no file), a gated::TRACK,::TAB/::SUBTABor::VIEWalternative is left out (#274). -
::SHOW_IF(DOCS, #515) hides a panel on the page only — there is no server-side gate for it, unlike-- @requiresabove: the condition and its target are ordinary statements the server answers through/api/panellike any other, whether or not the condition currently holds. -
::GUIDE_STEP/::GATE(DOCS, #516) are page navigation, same as::SHOW_IF— not access control. A gated or not-yet-reached step's statements are ordinary statements too;/api/panelanswers them the same whether the gate holds or not. The step variable is an ordinary viewer variable (a typed literal, like any input's): list it in-- @varsif the dashboard declares one, the same as any other viewer-settable name. -
A panel's
::TITLEis drawn as a title bar above its chart (first non-NULL value, trimmed and escaped, at most 200 characters; none on a KPI tile), as on a dashboard card. -
A panel whose query fails answers
400with a generic message ("this dashboard could not be shown (the server log has the details)"). The DuckDB error, which can quote file paths, SQL and values, goes to the server's stderr only ([anofox-serve] dashboard '<id>' failed: …, escaped, at most 512 characters). A timeout and the--max-rowscap still say what happened. -
--auth '<json>'(or--auth @auth.json) — login via an auth proxy, the same object asoptions.authbelow;--log <path|stderr>and--log-vars none|names|values— the request log. With--auththe render cache (--cache) is kept per viewer; it holds at most 1,024 pages / 64 MiB (oldest first out) and drops expired pages. A non-loopback--bindwithout--authprints aWARNING. A request target with a control character is400. The render server has no access policies (only the locked server does), so with--authevery panel has to filter on the claims itself. -
Ask (
--ask '<json>'or--ask @ask.json, #195). The same object and limits as the locked server'soptions.ask(below, Ask: questions about a dashboard), with these differences for this script-free page:- A login is required: the start fails without
--auth, andask.anonymousis refused here (a loopback bind behind a proxy is public too).--threadsmust be 2 or more. - The dashboard needs
-- @ask on. Then the page ends with an Ask form: the question, the notice (the provider, the operator'snotice, and whether questions are logged), the page's@paramvalues. API keys and share links get no form; signed embed links only withask.embed. POST /d/<id>/askanswers with the same dashboard page, the answer on top: escaped text (no link, image or markup of the model's), its verified citations as links to the cited panel (#panel-<n>; with other param values,/d/<id>?…#panel-<n>), the rest marked not verified, and a follow-up form naming the server-held conversation (never a history).Cache-Control: no-store, private; never cached.- The assistant's variables are the
@params:get_panelmay set a declared param to one of its listed values, nothing else (no inputs, no claims, no-- @varshere). A panel is read by rendering this page for those values with the asking viewer's claims and credential: a panel the page doesn't show them (-- @requires,::SHOW_IF, a later::VIEWalternative) is not available to the assistant either. Paging (::PAGED) isn't. - CSRF: the form carries a token (an HMAC of the viewer's claims and
the dashboard, keyed by a secret new at every start: a restart expires
open forms), and the post must be same-origin (
Origin, andSec-Fetch-Sitewhen the browser sends it). - A question holds an HTTP worker while it runs (up to
ask.timeout_seconds, 60 by default): at mostmin(ask.concurrency, --threads − 1)run at once (more get429), so pages always have a worker. - No row/column policies here: with Ask on, every panel must still filter on the claims itself — that is what keeps another viewer's rows out of the model's reads too.
- A login is required: the start fails without
Try it: serve --dashboards examples/serve-dashboards/dash --init examples/serve-dashboards/init.sql → http://127.0.0.1:8080/.
Not a server at all — a build step. Turns a folder anofox_serve_dashboards(dir, port[, options]) (mode A) would open into a folder of static files: HTML,
CSS, JS, the DuckDB-Wasm renderer, the dashboards' own .sql text, and a
copy (or a URL) of the data. Upload it to GitHub Pages, S3, or any plain web
server — there is nothing to run, and no TLS/auth/process-isolation
concerns from the rest of this document apply, because there is no process.
dashboard --site <folder> <out-dir> [--data <dir|url>] [--options locked.json] [--app <web dir|tarball>] [--basemap <json|file>]
<folder>is the same dashboard folderanofox_serve_dashboardsopens.--siterefuses it for the same reasons the locked server would refuse to start:dashboard --check <folder>'s own lint must pass, and (with--data) every dashboard statement must be read-only, checked with DuckDB'sjson_serialize_sql— the same ruleoptions.dataenforces on a locked server.--options locked.jsonaccepts the locked server's own options file unedited (#501) — the same file that opens the folder withanofox_serve_dashboards. It uses the keys that make sense with no server behind the pages:path_vars,nav_picker,app,home,theme. Server-only limits (max_rows,timeout_ms,threads,max_queries,cache_mb,memory_limit,data,hosts, …) have no effect without a server and are ignored, named once on stderr (e.g.--options: ignored for --site: max_rows, threads) so a typo among them doesn't vanish silently. An unknown key (not one ofanofox_serve_dashboards's options at all) is refused, same as the locked server refuses it. Notauthorpolicy, though — still refused, deliberately: a published site has no login and no row/column policy, so a site built from a file that has either would publish exactly what that policy was meant to hide. Every dashboard query the browser can build from the author's own SQL is what a viewer can see, as in the browser-only builder — say so if the data is sensitive, since a published site's data is public to anyone with the URL.--data <dir>is copied intoout/data/;--data <url>is read from there directly (nothing is downloaded by this command). Either way, the generated pagesSET VARIABLE anofox_data = '<url>'before every dashboard, exactly like a locked server'sgetvariable('anofox_data')— dashboard SQL doesn't need to know it's no longer talking to a server.- DuckDB-Wasm from the site itself (#832). The release's web build
(
--app) carries DuckDB-Wasm (vendor/duckdb-wasm/, about 37 MB, pinned:scripts/fetch-duckdb-wasm.sh), so a published site loads it from its own origin: the host's cache, one TLS connection, and no request to jsdelivr — it works behind an auth proxy that blocks third-party hosts. An--appwithout it (a plain checkout ofweb/) falls back to jsdelivr. Core DuckDB extensions (parquet, …) still come fromextensions.duckdb.org. - Each dashboard on its own connection (#836). Switching dashboards in a
site happens in place (no page load), but on a fresh DuckDB connection:
the
TEMPtables, views and macros and the variables of the dashboard being left go with it, as on the locked server, so two dashboards may use the same names. The database stays warm (extensions, the data files read once). - Performance (#830). In the browser a
read_parquetover a URL is a fresh set of HTTP requests, and aTEMP VIEWover it reads the file again for every panel that uses it. With--data <dir>,site.jsonlists the copied files (dataFiles) and the page reads each one once: the first statement that names it (… || '/sales.parquet') fetches it, and every later read, views included, is served from memory, across dashboard switches too.anofox_datais then a local name (anofox-site-data), not the URL. Files no statement names are never fetched; above 192 MB in all, the rest are read over HTTP (DuckDB's HTTP metadata and object caches on). So the locked server's advice — views overread_parquetin setup, notTEMP TABLEs — holds for a site too. With--data <url>nothing is listed and every read goes over HTTP: there, oneCREATE TEMP TABLE … AS FROM read_parquet(…)per file at the top is much faster than views. - The built-in map boundaries (
::REGION, a named::BASEMAP) are copied from--appintoout/data/boundaries/(#655), so a local--datafolder must not have its own top-levelboundariesentry (refused). nav_picker's options are computed now, by runningoptions.nav_picker.sqlagainst--datawith theduckdbCLI (the same read-only check, and the same "a value isn't a plain name → dropped" rule, as the locked server'sbuild_nav_picker) — never at request time (there are no requests). Refresh the site (re-run--site) to pick up new options.--app <web dir|tarball>is the browser app: unpacked, or theanofox-visualization-web-<tag>.tar.gzrelease asset as-is. Without--app, this command looks for aweb/folder next to its own binary and never downloads anything itself — a CI workflow fetches the release asset withgh release download(see the Action below) before running--site.--basemap <json|file>(#946): theoptions.basemapobject (or a file holding it, as fordashboard --svg --basemap). For every dashboard with a'on'::MAPTILESmap,--siteruns it once (inputs at their defaults), works out the tiles the page draws at its render widths, fetches them (at mostupstream_per_minutea minute from anhttps://source) and writes them into the site astiles/<z>/<x>/<y>;site.jsongets the attribution andmax_zoom. The published page reads its tiles from there — nothing loads from the tile source when someone views the site (T6 of the basemap review). A view the reader zooms or pans past the prefetched set, or a filter that moves the map elsewhere, draws without tiles. More than 3000 tiles stop the build: tile servers forbid bulk downloads (OpenStreetMap's public servers among them) — narrow the maps, lowermax_zoom, or use your own tile server. Without--basemapa::MAPTILESmap draws no tiles on the site.- Every path the generated site writes is relative, so it works from a
bucket root or a GitHub project-pages sub-path (
https://you.github.io/<repo>/) without configuration. - Output:
index.html(thehomedashboard, or the first by-- @order), oned/<id>/index.htmllauncher per dashboard (so a refresh, a shared/d/<id>?v.x=…link, and the browser's back/forward all land on a real file — GitHub Pages has no server-side rewrites),dashboards/<id>.sql,site.json(nav,path_vars, the computednav_pickeroptions,app,theme,home, and where the data is), anddata/(unless--datawas a URL).
What runs where. The published app is the same web/ build as every
other mode, with one addition: a page --site writes carries <body class="mode-view embed published"> (so there is no editor flash — the class
is in the markup from the first paint, not added by JS after the sidebar
painted) and <meta name="anofox-site" content="site.json">. That meta tag
is the only trigger for published mode — never a URL parameter, so a link
can never point the app at a different site.json and relabel someone
else's data as this site's own. On load, the app fetches site.json and the
current dashboard's .sql, then renders and queries locally, in
DuckDB-Wasm, exactly as the browser-only builder does — there is no
/api/panel to ask. Clicking a nav link, a nav_picker option, or a
/d/<id>?v.x=… ::LINK switches dashboards in place (history.pushState):
the DuckDB-Wasm session and any loaded data stay warm, so only the first
dashboard pays Wasm start-up.
The path-value rule. A path_vars value still has to be a plain name —
[A-Za-z0-9_.-], not starting with . — before the page will set it,
exactly the rule a locked server's check_path_values enforces on every
request. On a published site this is enforced client-side (there is no
server to enforce it instead): it keeps getvariable('anofox_data') || '/' || getvariable('model')-style dashboard SQL inside the site's own data/
folder even though nothing is checking requests, because nothing ever builds
that path from anything but a plain name.
The CSP. GitHub Pages (and most static hosts) can't set response
headers, so the server's CSP header becomes a <meta http-equiv="Content-Security-Policy"> in the generated HTML instead — the
same policy, minus frame-ancestors (a <meta> can't carry it) and the
per-response script nonce (a published page has no inline <script>:
script-src 'self' covers the one external app.js every page loads). It
differs from the locked server's page_csp in one way: connect-src /
script-src allow the whole cdn.jsdelivr.net/npm/ path, not individually
pinned package versions — a published page runs every query in the browser's
own DuckDB-Wasm, and DuckDB-Wasm's own +esm bundle pulls in apache-arrow,
which pulls in more packages of its own, each its own versioned
cdn.jsdelivr.net/npm/<pkg>@<version>/+esm script; pinning each one by exact
version is a chase a routine dependency bump always wins. A remote --data <url>'s own origin is added to connect-src too — the rule is "no request
to any host but this site's own origin and the data URL", not "no request
anywhere".
A GitHub Pages workflow (data refresh → --site → deploy):
name: Publish dashboards
on:
schedule: [{ cron: "0 6 * * *" }] # or push, workflow_dispatch, …
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Refresh the data
run: ./scripts/refresh-data.sh data/ # whatever produces your parquet/csv
- name: Fetch the released CLI + web app
env: { GH_TOKEN: ${{ github.token }} }
run: |
gh release download --repo DataZooDE/anofox-visualization --pattern 'anofox-visualization-cli-*-x86_64-unknown-linux-gnu.tar.gz' -O cli.tar.gz
gh release download --repo DataZooDE/anofox-visualization --pattern 'anofox-visualization-web-*.tar.gz' -O web.tar.gz
mkdir cli web && tar -xzf cli.tar.gz -C cli --strip-components=1 && tar -xzf web.tar.gz -C web --strip-components=1
- name: Build the site
run: ./cli/dashboard --site dash site --data data --options locked.json --app web
- uses: actions/configure-pages@v5
- uses: actions/upload-pages-artifact@v3
with: { path: site }
- uses: actions/deploy-pages@v4What differs from the locked server: no login, no row/column policy (say so
if the data is sensitive — it's public); nav_picker's options are frozen
at build time (refresh the site to update them); there is no /health or
request log, because there is no process to ask.
A static site can offer the in-page Ask (questions about the dashboard on the screen; not the assistant that edits) through a model endpoint you run on the site's own origin — a Cloudflare Pages Function, a Worker, a small proxy route — so the model key never ships in the published files:
{"site_ask": {"endpoint": "/api/llm", "model": "gemini-2.5-flash"}}endpointis a path on the site's own origin (/then letters, digits,-_.); another origin, a query,..or akey/tokenfield is refused when the site is built. The page posts OpenAI-stylePOST <endpoint>/chat/completions(non-streaming, withtools/tool_calls), sends the viewer's cookies along (credentials: "same-origin", so an auth proxy such as Cloudflare Access sees who asks) and noAuthorizationheader — the endpoint adds the key.- Ask shows only on dashboards whose header says
-- @ask on(and, as on the locked server,-- @vars); site.json lists them.-- @ask skip/maskand the personal-data masking work as in the builder. - It runs the panels in the page and sends the question, the view and the rows of the panels it reads to your endpoint; the viewer sees that in the notice before the first question. Answers see only what this viewer's page can query — on a static site that is everything the site serves.
- What the endpoint should do: check the viewer (the auth proxy's header or cookie), keep a per-user budget, allow only the configured model(s), forward to the provider with the key from its own secret store, and log as your policy says. The page enforces none of that.
- The site's CSP already allows
connect-src 'self'; nothing else changes.
- DNS rebinding. The
Hostmust be a loopback name on the server's port, the--bindaddress, or a name given with--allow-host NAME(repeatable;*disables the check); anything else gets421. Behind a proxy that forwards the originalHost, pass its public name with--allow-host.
DuckDB has no users, roles, GRANT or row-level security, so who sees what is
enforced by the server. Phase 1 takes the viewer's identity from an auth
proxy that already does the login (oauth2-proxy, Caddy forward_auth, nginx
auth_request, Cloudflare Access, …) and hands it to the dashboard SQL.
SELECT anofox_serve_dashboards('dashboards', 8095, '{
"hosts": ["dash.example.com"],
"auth": {
"mode": "proxy",
"shared_secret_env": "ANOFOX_PROXY_SECRET",
"trusted_proxies": ["127.0.0.1"],
"header_user": "X-Forwarded-User",
"header_groups": "X-Forwarded-Groups",
"claims": {"tenant": {"header": "X-Forwarded-Tenant", "required": true}}
},
"policy": "/etc/anofox/policy.json",
"log": "/var/log/anofox/requests.jsonl"
}');With auth, the server needs an access policy (policy, or policy.json
in the dashboard folder — see
Row and column policies), or an
explicit "policy": "none" to rely on claim filters in the panels as below;
otherwise it refuses to start.
auth key |
Default | Meaning |
|---|---|---|
mode |
(required) | "proxy" (the other modes — jwt, oidc, embed, api_keys — are under Built-in login) |
shared_secret / shared_secret_env |
(one is required) | The secret the proxy sends on every request; ≥ 32 printable characters (openssl rand -hex 32). Prefer shared_secret_env (the name of an environment variable of the DuckDB process): a literal in the SQL ends up in shell history and query logs |
secret_header |
X-Anofox-Proxy-Secret |
Header carrying the secret |
trusted_proxies |
key absent: any peer | Addresses / CIDR ranges (10.0.0.0/8, ::1) the proxy connects from; any other peer is refused even with the right secret. An empty list is an error. Write IPv4 ranges as IPv4 (::ffff:… forms are rejected; IPv4-mapped peers are matched as IPv4) |
header_user |
X-Forwarded-User |
Header with the user name / e-mail (required, non-empty) |
header_groups |
off (null) |
Opt-in. Groups header, split on groups_separator (default ,) |
claims |
— | Extra claims → __claim_<name> (up to 16): {name: "Header"} or {name: {"header": "Header", "required": true}} |
header_groups takes the same {"header": …, "required": true} form. A
required claim that is absent or empty is 401 (deny: missing_claim);
otherwise an absent claim is NULL (groups: []). The start message lists the
identity headers the server trusts — compare it with the proxy configuration.
How a request is checked. With auth set, every request except GET /health (/healthz; it answers {"status":"ok"} without a login and its full
body only with one) must (1) come from a trusted_proxies address (when given), (2) carry
the shared secret exactly once (constant-time comparison), and (3) carry a
non-empty user header exactly once. Otherwise the answer is 401 with the same
body for every reason (the reason goes to the request log only). Identity
headers are read only after the secret checks out, so identity headers a
client sends directly are never believed. A repeated identity header (a proxy
that appends instead of replacing) is refused rather than guessed at. A broken
auth object fails the server start: the server never falls back to serving
without login.
The secret proves that a request came through the proxy — not that the proxy wrote every header in it. A proxy forwards the client's other headers, so every configured identity header (user, groups, each claim) must be set or removed by the proxy on every request; one it leaves alone reaches the server with the client's value. That is why groups and extra claims are opt-in: configure only headers your proxy controls (the recipes below do this for each header they name).
Claims are reserved variables. After the viewer's own variables, the server sets, on the request's private connection:
| Variable | Type | Value |
|---|---|---|
__claim_user |
VARCHAR |
the user header |
__claim_groups |
VARCHAR[] |
the groups, trimmed, sorted, deduplicated ([] if none) |
__claim_<name> |
VARCHAR |
each claims header (NULL if absent) |
All three are typed literals like any variable value. A viewer can never
set a __claim_* variable (any case): a panel request naming one is 400, a
-- @param or -- @vars entry naming one is ignored, and the browser client
ignores ?v.__claim_* in the URL. The same holds for anofox_data (the data
folder, see above), whether or not a data folder is configured. Without auth
the claims are simply unset
(NULL), so a panel that filters on them returns no rows instead of every row.
-- rows of the viewer's regions; the 'admins' group sees all
SELECT region::XAXIS, sum(revenue)::BARCHART FROM orders
WHERE region IN (SELECT region FROM entitlements WHERE viewer = getvariable('__claim_user'))
OR list_contains(getvariable('__claim_groups'), 'admins')
GROUP BY region;Only filter on claims, never on viewer variables. Any variable that is not
a claim is set by the viewer and can hold any value. A column that raises an
error() is not an access control either: a ::PAGED table's requests (count,
distinct values, stats, a page without its ::INFO column) evaluate only the
columns they need — put access rules in a WHERE on the claims or in the
policy. Optionally restrict the
viewer-settable variables of a dashboard with a header line
-- @vars region, channel, selected; variables not listed are dropped (never
set) on a locked server. List the dashboard's inputs, named selections and
selected (the client sends the shared click selection).
The dashboard's own SET VARIABLEs run after the viewer's values. Every
panel request sets the viewer's values (typed literals), then re-runs the
dashboard's setup statements before that panel, best effort (a failing one is
logged and skipped): a plain SET VARIABLE x = … overrides a viewer's x
only when it succeeds — one that reads another viewer-settable variable can be
made to fail — so it is a default, never an access rule. A default such as
SET VARIABLE x = coalesce(nullif(getvariable('x'), ''), (SELECT max(run) FROM runs)) keeps the viewer's x. Restrict what viewers can set with -- @vars,
and filter on claims. The browser sends only what the viewer set (inputs,
selections, ?v. values) — never a dashboard's own SET VARIABLE text.
Per-viewer caching. The result cache and the single-flight key include the
viewer's claims (user, groups, every extra claim), so a result computed for one
viewer is never served to — and a running query never shared with — a viewer
with different claims. The claims are always part of the key in full, whatever
variables a panel reads — the access policy's row filters read them. A
credential's locked variables (an embed link, a page session) are likewise
always in the key, never narrowed by what a panel reads — they act like
authorization — and are canonicalized the same way as the request's own
(the later of two spellings of one name wins), so two tokens that lock the
same name differently always get different keys. The static server's
--cache key includes the claims too. Supersession tickets are scoped to the
user as well.
The proxy must authenticate every request, set or remove every configured
identity header (never append, never pass the client's through), add the
secret, and be the only way to reach the server. Keep the server on loopback
(or on a private network with trusted_proxies). The nginx, Caddy and
oauth2-proxy configs below were checked with nginx -t, caddy validate and
oauth2-proxy's strict config loader. The nginx and Caddy recipes were also run
in front of a server, with a stand-in for oauth2-proxy's /oauth2/auth, while
a client sent forged X-Forwarded-User, X-Forwarded-Groups and
X-Forwarded-Tenant: the server saw only the proxy's values (and no groups or
tenant when the login had none).
nginx + oauth2-proxy (auth_request). proxy_set_header replaces the client's
header, and with an empty value nginx sends no header at all. So every identity
header gets a proxy_set_header line, even one the IdP may not return:
location = /oauth2/auth {
internal;
proxy_pass http://127.0.0.1:4180;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
}
location / {
auth_request /oauth2/auth;
auth_request_set $user $upstream_http_x_auth_request_email;
auth_request_set $groups $upstream_http_x_auth_request_groups;
auth_request_set $tenant $upstream_http_x_auth_request_tenant;
proxy_set_header X-Forwarded-User $user; # set or removed, never the client's
proxy_set_header X-Forwarded-Groups $groups; # (only if header_groups is set)
proxy_set_header X-Forwarded-Tenant $tenant; # one line per claims header
proxy_set_header X-Anofox-Proxy-Secret "<secret>";
proxy_set_header Host $http_host; # with its port; list it in options.hosts
proxy_pass http://127.0.0.1:8095;
}(Plus oauth2-proxy's own location /oauth2/ { proxy_pass http://127.0.0.1:4180; }
and error_page 401 = /oauth2/sign_in; for the login redirect.)
Caddy (forward_auth). Delete every identity header first, inside a route
block so the directives run in the written order (outside route, Caddy sorts
them). copy_headers then sets the ones the auth response carries:
dash.example.com {
route {
request_header -X-Forwarded-User
request_header -X-Forwarded-Groups
request_header -X-Forwarded-Tenant
forward_auth 127.0.0.1:4180 {
uri /oauth2/auth
copy_headers X-Auth-Request-Email>X-Forwarded-User X-Auth-Request-Groups>X-Forwarded-Groups X-Auth-Request-Tenant>X-Forwarded-Tenant
}
request_header X-Anofox-Proxy-Secret {env.ANOFOX_PROXY_SECRET}
reverse_proxy 127.0.0.1:8095
}
}oauth2-proxy on its own (alpha config). oauth2-proxy removes each
injectRequestHeaders header from the client's request before setting it
(preserveRequestValue: false is the default), and joins multi-valued claims
such as groups with ,:
upstreamConfig:
upstreams:
- id: anofox
path: /
uri: http://127.0.0.1:8095
injectRequestHeaders:
- name: X-Forwarded-User
values:
- claimSource:
claim: email
- name: X-Forwarded-Groups # only with "header_groups": "X-Forwarded-Groups"
values:
- claimSource:
claim: groups
- name: X-Anofox-Proxy-Secret
values:
- secretSource:
fromFile: /etc/anofox/proxy-secretCloudflare Access (not tested here): Access sets
Cf-Access-Authenticated-User-Email on requests it has authenticated. Use it as
the only identity header: "header_user": "Cf-Access-Authenticated-User-Email",
with no header_groups and no claims, because Cloudflare passes other
client headers such as X-Forwarded-Groups through to the origin. Add the
secret with a Transform Rule (Modify Request Header → Set static, which
replaces a client's value), and let only cloudflared reach the server. Groups
or other claims from Access require verifying the signed
Cf-Access-Jwt-Assertion, which is P3 (#50).
Folded headers (obs-fold). An HTTP/1.1 header line that starts with a space
or tab continues the previous header (obsolete line folding, RFC 9112 §5.2).
The server's HTTP parser does not unfold such a line; it reads it as a
header of its own. A proxy that forwarded folded lines unchanged would
therefore let a client add identity headers the proxy never saw. The proxy must
reject folded headers or unfold them before forwarding, as RFC 9112 requires.
Both were checked: nginx answers 400, and Caddy (Go) unfolds the line into
the previous header's value.
"log": "/var/log/anofox/requests.jsonl" (or "stderr"; serve: --log)
appends one JSON object per line for page views, /api/panel requests and
every refused request (static assets are not logged):
{"ts":"2026-10-16T20:47:19.487Z","user":"alice@example.com","method":"POST","path":"/api/panel","status":200,"ms":25,"dashboard":"rls","panel":1,"cache":"run","bytes":68,"peer":"127.0.0.1","vars":["channel"]}
{"ts":"2026-10-16T20:47:19.762Z","user":null,"method":"POST","path":"/api/panel","status":401,"ms":0,"peer":"127.0.0.1","deny":"bad_secret","vars":[]}tsUTC,mslatency,cache=hit/shared(joined a running identical query) /run,bytes= response size,deny=untrusted_peer/bad_secret/no_user/missing_claim/malformed_identity.log_vars(--log-vars):"names"(default) logs variable names only;"values"logs their SQL literals (may be personal data — opt in);"none"omits them. The path is logged without its query string. Headers, cookies, the secret and claims other than the user are never logged.- The file is created
0600(an existing file readable by others is set to0600), never through a symlink (O_NOFOLLOW), and reopened for every line, so a rename-based rotation needs no signal (logrotate:daily,rotate 14,compress,delaycompress, nocopytruncateneeded). Each line is onewritewithO_APPEND. - With
"stderr", the server's plain diagnostics share the stream; they start with[anofox-serve]and escape every control character in request data (a newline is written as\n), so only the request log writes lines that start with{. A request target containing a control character is400.
The server can sign viewers in without an auth proxy. auth takes one method
object or a list of them (each mode at most once). Every method ends in
the same claims as the proxy (__claim_user, __claim_groups,
__claim_<name>), set the same way and in the same order, so panels,
policies, the per-viewer cache and the request log don't care how a viewer
signed in.
SELECT anofox_serve_dashboards('dashboards', 8095, '{
"hosts": ["dash.example.com"],
"auth": [
{"mode": "oidc", "issuer": "https://login.example.com", "client_id": "dashboards",
"client_secret_env": "OIDC_CLIENT_SECRET",
"redirect_url": "https://dash.example.com/auth/callback",
"groups_claim": "groups", "claims": {"tenant": "tid"},
"session_secret_env": "ANOFOX_SESSION_SECRET"},
{"mode": "jwt", "issuer": "https://login.example.com", "audience": "dashboards-api"},
{"mode": "embed", "secret_env": "ANOFOX_EMBED_SECRET", "claims": ["tenant"]},
{"mode": "api_keys", "file": "/etc/anofox/keys.json"}
],
"policy": "/etc/anofox/policy.json",
"audit": "/var/log/anofox/audit.jsonl",
"log": "/var/log/anofox/requests.jsonl"
}');serve --dashboards takes the same --auth methods, but it has no row
and column policies (#49 / policy is only in anofox_serve_dashboards):
there every panel must filter on getvariable('__claim_*') itself; its start
message says so.
Which credential counts. Exactly one per request, the first present of:
an embed link (GET /d/<id>?embed=<token>), the proxy's secret header, an
Authorization header, an embed page session (X-Anofox-Session), the login
cookie, a JWT cookie. A credential that is present but invalid is refused
(401) — the server never falls back to the next one. Without any
credential a page view (/, /d/…) is sent to /auth/login when oidc is
configured, everything else is 401. With proxy as the only method,
behaviour is exactly P1. A broken auth (an unknown key, a missing or short
secret, one secret used for two roles, an http:// issuer, an HS* or none
algorithm, an unreadable key file, …) fails the server start. Every secret
plays one role: the embed link secret, the proxy's shared secret and the
session secrets must all differ (the OIDC and embed session secrets may be
the same value; their keys are derived per use).
| key | default | meaning |
|---|---|---|
issuer |
(required) | The IdP's issuer URL, https:// only; a token's iss must equal it exactly |
audience |
(required) | This server's audience (string or list); aud must contain one |
jwks_url |
discovered | The key set; otherwise jwks_uri from <issuer>/.well-known/openid-configuration (whose issuer must match). https:// only |
algorithms |
["RS256", "ES256", "EdDSA"] |
Allowed: RS256/384/512, PS256/384/512, ES256, ES384, EdDSA. HS* and none are rejected at startup |
leeway_s |
60 |
Clock skew for exp, nbf, iat (at most 300) |
max_age_s |
— | Refuse tokens issued longer ago (requires iat) |
jwks_ttl_s |
3600 |
Key-set cache lifetime (60–86400) |
require |
— | Claim values a token must carry, checked after the signature: {"tid": "acme"}, or a list of accepted values; a list claim (groups) must hold one of them. Pins a tenant of a shared identity provider (#864); required for agent.mcp |
user_claim |
sub |
Token field → __claim_user. If it is an e-mail field (email, or a path or namespaced name ending in it, like profile.email), the token must also carry email_verified: true (deny: email_unverified): an address the IdP did not verify is no identity (nOAuth). The same holds for a claims entry taken from an e-mail field. Other fields some IdPs let users change (Entra ID's preferred_username and upn) are no stable identity: prefer sub or oid |
groups_claim |
off | Token field (list or string) → __claim_groups; {"field": …, "required": true} makes it mandatory |
claims |
— | {name: "field"} → __claim_<name>; dotted paths (realm_access.roles) and namespaced fields (https://example.com/tenant) work |
cookie |
— | Also read the token from this cookie |
accept_id_tokens |
false |
Accept OIDC ID tokens (a nonce, at_hash, c_hash, token_use: "id" or typ: "ID" claim, unless the header's typ is at+jwt) as bearer tokens. Off: an ID token is a login receipt for one client, not an API credential (deny: id_token). With oidc configured too, an audience equal to its client_id fails the start unless this is set |
ca_file |
Mozilla roots | PEM roots for an internal IdP (replaces the public roots) |
How a token is checked: compact JWS only; the header's alg must be one of
algorithms (asymmetric only: a token signed with HS256 — e.g. with the
public key as the secret — is refused before a key is looked at); a crit
header is refused; jku, x5u and an embedded jwk are ignored, keys come
only from the configured key set. The kid must name a key of the set (a
token without kid is accepted only while the set has exactly one key), and
each key verifies only the algorithms of its own type and curve (and its JWK
alg, if given); symmetric (oct) JWKs, RSA keys under 2048 bits and keys
with "use": "enc" are never loaded. exp, iss and aud are required; nbf
and iat must not be in the future. The key set is fetched over HTTPS (no
redirects, 10 s timeout, 1 MiB cap), cached for jwks_ttl_s, refetched for an
unknown kid at most every 30 s (so random kids can't make the server
hammer the IdP), and dropped when it could not be refreshed for 24 h — then
every token is refused until the IdP is back (fail closed). The variable
names come from the configuration; a token supplies only values, which are
length-checked, refused when they contain control characters, and bound as
typed literals — a field called __claim_user in a token is just
an unknown field.
The authorization code flow with PKCE. Takes the jwt keys for the ID token
(issuer, algorithms, leeway_s, jwks_url, …; the audience is the
client_id) plus:
| key | default | meaning |
|---|---|---|
client_id |
(required) | The client registered at the IdP |
client_secret_env / client_secret |
— | A confidential client's secret (sent with HTTP Basic); omit for a public client (PKCE only) |
redirect_url |
(required) | https://<this server>/auth/callback — register it at the IdP. http:// only for 127.0.0.1 / localhost |
scopes |
["openid", "email", "profile"] |
Must include openid |
user_claim |
email |
as for jwt (also groups_claim, claims); email requires email_verified: true in the ID token, else the login fails (email_unverified) |
session_ttl_s |
28800 (8 h) |
Session lifetime, 60 s … 7 days |
session_secret_env |
random per start | ≥ 32 characters; sign sessions with it so they survive a restart and work on every replica (#22). Without it, a restart signs everyone out |
post_logout_url |
/auth/logged-out |
Where POST /auth/logout sends the browser |
revocation_file |
— | Keep logouts in this file (JSON lines, 0600, never through a symlink; expired lines are dropped at start): they survive a restart, and replicas sharing the file see each other's within 2 s. If the file disappears, can't be read or becomes writable by group or others, every login session is answered 503 (Retry-After, deny: revocations_unavailable, no login redirect) until it is fixed (fail closed; reported on stderr and as revocation_file / error in the audit log). Every write — a logout, and the compaction of expired lines at start — holds an exclusive lock on <file>.lock (created 0600 next to it), so no replica's logout lands in a file that is being replaced. A logout while the file is unavailable is still recorded: the server checks the cookie's signature only, refuses the session in memory, and writes the line once the file is back; a logout never recreates a file that is gone, and the file is created only on the very first start: if <file>.lock exists but the file doesn't, the server refuses to start (restore the file, or delete the .lock file to start with no revocations). A logout that can't take the lock within about a second, or can't write, stays queued and is retried; the failure is reported on stderr and once as revocation_file / error (write_failed) in the audit log. Rotate it safely: write the new file next to it and rename it into place while holding the lock (flock revoked.jsonl.lock mv revoked.new revoked.jsonl) — never move the old file away first (meanwhile every session would be refused, and logouts written to the moved file would be lost) |
GET /auth/login?next=/d/salescreates a randomstate,nonceand PKCE verifier, keeps them in a signedHttpOnly; Secure; SameSite=Laxcookie (__Host-anofox_oidc, 10 minutes) and redirects to the IdP (S256 challenge).nextmust be a local path (/…, never//hostor a scheme): no open redirect.GET /auth/callbackchecksstateagainst the cookie (constant time), exchanges the code (with the verifier and the client secret, HTTPS only), verifies the ID token like a bearer token (aud=client_id,azpwhen there are several audiences) and itsnonceagainst the cookie. The state cookie is cleared: a callback URL can't be replayed.- The session is a server-signed token (HS256,
session_secret_envor a random key) holding the claims, a random session id and the expiry, in__Host-anofox_session(HttpOnly; Secure; SameSite=Lax; Path=/). The expiry is checked by the server on every request. Two session cookies in one request (cookie tossing from a sibling domain) are refused. Replicas stay stateless. POST /auth/logout(same-origin only;GETshows a button, so a link on another site can't sign anyone out) revokes the session id and clears the cookie. Withoutrevocation_file, a revocation is held in memory by the replica that handled it: a restart forgets it and other replicas accept the session until it expires. With it, logouts are durable and shared by the replicas that use the same file. Keepsession_ttl_sshort either way: a session token is valid until it expires everywhere it isn't revoked.
Cookies are Secure: serve over HTTPS (TLS at the reverse proxy); browsers
also accept them on http://localhost.
A host application embeds a dashboard for its own signed-in user without a second login (like Metabase static embedding or Superset guest tokens). It signs, with a secret it shares with this server (HS256, any JWT library):
{"dashboard": "sales", "user": "acme:42", "groups": ["viewer"],
"claims": {"tenant": "acme"}, "vars": {"region": "EU"},
"exp": 1792152300, "jti": "8c1f…"}and links to /d/sales?embed=<token> (e.g. as an iframe's src).
| key | default | meaning |
|---|---|---|
secret_env / secret |
(required) | ≥ 32 characters, shared with the host application only |
claims |
[] |
Claim names a link may set (__claim_<name>); any other name is refused |
max_link_ttl_s |
300 |
A link's exp may be at most this far ahead (≤ 1 day) |
session_ttl_s |
3600 |
The page session's lifetime (≤ 1 day) |
one_time |
false |
Accept a link (it must carry a jti) once per server process |
leeway_s |
30 |
Clock skew |
session_secret_env |
random per start | Signs page sessions. Must differ from secret (the host must not be able to mint sessions) |
The server checks the signature (constant time), requires exp, refuses
links valid for longer than max_link_ttl_s, unknown fields, claim names not
in claims, and variable names that are not identifiers or are reserved
(__claim_*, anofox_data). The link must name this dashboard. It is then
exchanged for a page session scoped to that one dashboard:
- The page gets the session in its config and sends it as
X-Anofox-Sessionon each/api/panelrequest — no third-party cookie, so it works in a cross-site iframe in every browser. The page then removes the link from its address (history.replaceState); a reload needs a fresh link. The page isCache-Control: no-storeandReferrer-Policy: same-origin(the link is in its URL: never sent to another site). - Scope can't be widened from the URL. The session reads only its
dashboard (others:
403; the navigation lists only it); the link'svarsare locked — the viewer's values for them are dropped and the link's are set after the viewer's variables (before the claims), so?v.region=USor a crafted panel request changes nothing. The session's scope and claims are signed by the server. Onserve --dashboards(no script), this also covers an::INPUT's own default: on the first render after exchanging the link, the dashboard's::DROPDOWN/etc. default-binds its variable for every downstreamgetvariable()panel (so they have something to read even without a script picking a value) — fixed (#540) to skip that bind entirely for a name the link already locked, same as it already skips one a whitelisted-- @paramset; before the fix, the default was bound after the lockedSET VARIABLEand won for the rest of that render. - The UI's code files (
.js,.css,.wasm, fonts) are served without a credential whenembedis configured — they are the open-source viewer, no data. Pages,/api/paneland data files still need one. serve --dashboards(no script) exchanges the link once and keeps the page session in a hidden field of the page's form, which itPOSTs to/d/<id>(application/x-www-form-urlencoded, same-origin only, answeredno-store): the session never appears in a URL, a history entry or a request/proxy log line, andone_timelinks work there too. A page session is never accepted from a query string (by either server).- A link without
usersigns in asembed:<dashboard>— not one shared user, and a form no proxy header, token or API key may claim (they are refused), so no IdP account can collide with it. /healthzanswers a scoped credential (an embed page, an API key limited to dashboards) with{"status":"ok"}only, like a request without login.- A locked variable listed in
path_varsmust be a plain file or folder name, like a viewer's.
Replay. Whoever has a link can use it until it expires, and a page
session until it expires: mint links per page view, keep max_link_ttl_s at
minutes and session_ttl_s at what a viewing needs, and serve over HTTPS.
one_time: true with a jti stops a second exchange of the same link on one
server process (with several replicas, a link can be used once per replica;
a page reload then needs a new link).
A web component for the host application, so it needs no signing code of its own and never holds the embed secret:
<script type="module" src="https://dash.example.com/sdk/anofox-embed.js"></script>
<anofox-dashboard src="https://dash.example.com/d/sales" token-callback="getToken"></anofox-dashboard>
<script>
// Your backend calls POST /api/auth/token with its API key; the browser only gets the token.
async function getToken(dashboard) {
return (await (await fetch("/my-backend/anofox-token?d=" + dashboard)).json()).token;
}
const d = document.querySelector("anofox-dashboard");
d.addEventListener("anofox-state", (e) => console.log(e.detail.vars)); // after every run
d.addEventListener("anofox-link", (e) => console.log(e.detail.href)); // a link out of it
d.setVars({ region: "EU" });
</script># the host's backend (its API key has the embed scope)
curl -X POST https://dash.example.com/api/auth/token -H "Authorization: Bearer $KEY" \
-H 'Content-Type: application/json' -d '{"dashboard": "sales", "vars": {"region": "EU"}}'
# {"token":"eyJ…","expires":1793000300,"url":"/d/sales?embed=eyJ…"}-
The token is a signed embed link like the ones a host signs itself (Signed embed links). It needs an
embedlogin (itssecretsigns it) and an API key with theembedscope, and it is capped by that key:- only the key's dashboards;
- exactly the key's claims (every claim the key has must be in the embed
mode's
claims, or the request is refused); - a subset of its groups;
- locked variables as asked;
ttl_sat mostmax_link_ttl_s.
A key with
tenant=acmecan't mint a token for another tenant. The token has no user of its own (its viewer isembed:<dashboard>, like a link without one), so it never submits or saves as somebody. -
The element keeps the dashboard in an iframe on the dashboard's own origin: its CSP stays in force, and its data never reaches the host page's scripts. It sizes the frame to the dashboard, asks
getTokenagain when the page's session ends, and passes messages both ways:anofox-ready;anofox-state {vars}after every run;anofox-link {href}for a link that leaves the dashboard (the frame doesn't navigate: the host decides);el.setVars({…}), applied as a?v.…link would be, so a variable the token locks keeps its locked value on the server.
The page takes and sends messages only from its parent and only to an origin in
frame_ancestorsthat is also its referrer. -
/sdk/anofox-embed.jsand/sdk/anofox-react.js(a React wrapper:makeAnofoxDashboard(React), propssrc,getToken,vars,onState,onLink) answer without a login and with CORS (Access-Control-Allow-Origin: *): they are code, with no data. -
Every token minted, or refused, is in the audit log (
"audit": "embed_token").
For scripts and server-to-server clients: Authorization: Bearer afx_<id>_<secret>
(12 hex digits of id, 256 random bits of secret).
serve api-key new --file /etc/anofox/keys.json --user svc-etl --groups etl \
--claim tenant=acme --dashboards sales,stock --expires-days 90 --audit audit.jsonl
# prints the key ONCE; the file stores only its SHA-256
serve api-key new --file /etc/anofox/keys.json --user svc-collector \
--dashboards '' --scopes ingest:events # writes events, reads no dashboard
serve api-key revoke --file /etc/anofox/keys.json --id 3f9c0a1b2c3d
serve api-key list --file /etc/anofox/keys.jsonWithout the serve binary, a key and its entry can be made by hand:
id=$(openssl rand -hex 6); key="afx_${id}_$(openssl rand -hex 32)"
printf %s "$key" | sha256sum # → "sha256" of the entry {"id": "$id", "sha256": …, "user": …}- The key file (
{"keys": [{"id", "sha256", "user", "groups", "claims", "dashboards", "scopes", "expires", "revoked", "note", "created"}]}) must not be writable by group or others; it holds hashes only (a 256-bit key needs no slow hash). Keys are scoped todashboards(absent = all) and expire atexpires(Unix seconds). - The id selects the entry, the hash is compared in constant time (also against a dummy for an unknown id).
- The server re-reads the file when it changes (checked at most every 2 s): a revocation takes effect without a restart. A file that stops parsing, or becomes group/world-writable, disables every key until it is fixed (fail closed) and is audited.
- A key never appears in a log; the audit log names its id.
A key reads the dashboards in its dashboards list and nothing else. Its
scopes add one right each:
| Scope | Lets the key | Route |
|---|---|---|
ingest:<table> (one per table) |
write rows into that table of the ingest database | POST /api/data/<table> (#769) |
preview |
create temporary dashboards, run under the key's own claims | POST /api/dashboards (#770) |
embed |
mint embed tokens, capped by the key's own claims and dashboards | POST /api/auth/token (#771) |
admin |
reload the dashboards | (#772) |
- A key without
scopeskeeps exactly the rights it always had. No other login method (proxy, JWT, OIDC, embed link, share link) carries scopes. - Each scope is checked only by its own route, and no scope implies
another:
admindoes not giveingest, andingest:eventsdoes not giveingest:orders. Table names are plain identifiers; there is no wildcard. - Scopes add to reading, they don't replace it. A key meant only to ingest
gets
"dashboards": [](--dashboards ''), or it also reads every dashboard (serve api-key newsays so). - An unknown scope name fails the whole file, like any other error in it (fail closed): a file written for a newer server never loads with fewer limits than its author meant.
- The routes come with the issues named in the table. Until a route ships, its scope opens nothing.
Open a dashboard of the locked server to anyone who has its link
("access": "public"), or to anyone who also knows its password
("access": "password") — without a login at an identity provider and
without a host application signing embed links.
{"mode": "share", "session_secret_env": "ANOFOX_SHARE_SESSION",
"dashboards": {
"sales": {"access": "public", "claims": {"tenant": "acme"}},
"ops": {"access": "password", "password_hash": "pbkdf2-sha256$600000$…$…",
"groups": ["partner"], "vars": {"region": "EU"}}}}serve share-password --generate # makes up a password, prints it ONCE, and its hash
printf '%s\n' "$PW" | serve share-password # the hash of your own (≥ 12 characters)| key | default | meaning |
|---|---|---|
dashboards |
(required) | The shared dashboards, by id. Every other dashboard, the list page / and the API without a page session stay closed to a share viewer |
dashboards.<id>.access |
(required) | "public" or "password" |
dashboards.<id>.password_hash |
pbkdf2-sha256$<iterations>$<salt>$<key> from serve share-password; never the password |
|
dashboards.<id>.groups / claims |
none | The share viewer's groups and claims (__claim_groups, __claim_<name>): the policies and the panels' claim filters apply as to any viewer |
dashboards.<id>.vars |
none | Locked variables, as an embed link's: set after the viewer's, whatever the URL asks for |
session_ttl_s |
28800 (8 h) |
How long a password login and a page session last (60 s – 7 days) |
session_secret_env |
random per start | Signs the login cookies and page sessions. Without it, logins end when the server restarts and don't carry over between replicas |
How it works:
- A share viewer is the user
share:<id>. No other login method can claim that name (the proxy, tokens, API keys and embed links are refused), and like an embed link's default user it never submits (::SUBMIT) or saves (::SAVE): it is one identity shared by everybody with the link. - A public dashboard's page and its
assets/open without any credential; the page gets a page session (X-Anofox-Session) for its requests, scoped to that one dashboard, as an embed link's page does. - A password-protected dashboard's page shows a password form (
POST /share/<id>, same-origin only). The right password sets__Secure-anofox_share—HttpOnly; Secure; SameSite=Lax; Path=/d/<id>, signed by the server, valid forsession_ttl_s— and goes back to the page it came from (only that dashboard's page: never another site). As with the OIDC login cookie,Securemeans the browser keeps it only over HTTPS (or onlocalhost). - Wrong passwords: at most 10 per client address and 100 per dashboard in 15
minutes (
429withRetry-Afterafter that, even for the right password); at most 4 checks at a time (503). Counted per replica. A password check takes PBKDF2-HMAC-SHA256 with 600,000 iterations. Behind a reverse proxy every viewer has the proxy's address: limit failedPOST /share/*there too. - Other logins come first: a viewer who also signed in another way (OIDC, a token, an embed link) is that identity on a shared dashboard too.
- The audit log records
share_login(ok,wrong_password,locked_out,busy) and the page sessions of password-protected dashboards (share) — never a password, and only configured dashboard ids. A public dashboard's page views are not audit events (the request log has them). - To revoke a password, replace its hash and restart; existing login cookies
stay valid until they expire unless
session_secret_envchanges too.
"audit": "/var/log/anofox/audit.jsonl" (serve: --audit; "stderr"
works too) appends one JSON object per authentication event and admin
action. It uses the request log's file handling (0600, O_NOFOLLOW,
reopened per line for rename-based rotation, one write per line).
{"ts":"2026-10-17T09:12:03.120Z","audit":"start","outcome":"ok","detail":"oidc,embed,api_keys"}
{"ts":"2026-10-17T09:12:41.882Z","audit":"login","outcome":"ok","method":"oidc","user":"alice@example.com","sid":"T3x…","peer":"127.0.0.1"}
{"ts":"2026-10-17T09:13:02.004Z","audit":"embed","outcome":"ok","method":"embed","user":"acme:42","dashboard":"sales","sid":"q9…","peer":"127.0.0.1"}
{"ts":"2026-10-17T09:13:15.551Z","audit":"auth","outcome":"deny","method":"api_key","reason":"revoked","key_id":"3f9c0a1b2c3d","path":"/api/panel","peer":"10.0.0.7"}
{"ts":"2026-10-17T09:14:00.310Z","audit":"logout","outcome":"ok","method":"oidc","user":"alice@example.com","sid":"T3x…"}
{"ts":"2026-10-17T09:15:00.000Z","audit":"api_key_revoked","outcome":"ok","key_id":"3f9c0a1b2c3d","user":"svc-etl","detail":"/etc/anofox/keys.json"}Events: start, login, logout, embed (a link exchanged), auth with
outcome: "ok" (each bearer token, API key or session the first time it is
used, then at most every 10 minutes per credential), auth with
outcome: "deny" (any refused credential, with its reason: expired, not_yet_valid,
bad_signature, bad_alg, bad_issuer, bad_audience, unknown_kid,
missing_claim, bad_claim (an auth.require value), malformed_token, revoked, unknown_key, out_of_scope,
email_unverified, id_token, session_ttl,
link_ttl, replayed, bad_state, bad_nonce, …), api_key_created,
api_key_revoked, api_keys_reloaded. Never logged: tokens, keys, cookies,
authorization codes, secrets. The request log gains "auth": the method that
signed the request in.
| Threat | Mitigation |
|---|---|
A client sends X-Forwarded-User: admin directly to the server |
No secret → 401; identity headers are only read after the secret matches. Keep the server reachable only by the proxy (loopback / private network + trusted_proxies) |
| A client sends identity headers through the proxy | The proxy must overwrite them (recipes above); a duplicated header is 401 |
| A client sends identity headers the proxy doesn't set (groups, extra claims) — the secret still matches | Groups and claims are opt-in (only header_user by default); the proxy must set or remove every configured header on every request (each recipe does; checked with forged headers through nginx and Caddy); required claims make a missing value 401; the start message lists the trusted headers |
| Folded (obs-fold) header lines smuggling an identity header past the proxy | The proxy must reject or unfold them (nginx: 400, Caddy: unfolds); the server can't tell a folded line from a header |
The secret leaks (config file, ps, SQL history) |
shared_secret_env, trusted_proxies as a second factor; the secret never appears in errors, Debug output or the log. Rotate by restarting with a new value |
| Brute-forcing the secret | ≥ 32 characters, constant-time comparison (no early return on a length mismatch either) |
A viewer sets __claim_user / __claim_groups / anofox_data (vars, ?v.*, a @param) |
Rejected (400) / ignored, in any case and in every configuration; claims and anofox_data are set by the server after the viewer's variables (a unit test pins this order) |
Snapshot refresh (refresh_s) mixing users or snapshots |
Each snapshot generation has its own cache; keys include the claims, supersession tickets the user (tested with two users under constant refreshes) |
/healthz leaks snapshot state |
With auth, only status without a login |
| A scheduled task (#767) writing where it shouldn't, or changing the serving session | Writes are refused by DuckDB outside tasks.write (the runner starts only when every other database is attached READ_ONLY); session-changing statements and file writes are refused when the task is read; tasks are files, never request input |
| An export (#764) reading more than the page could | Each panel goes through the page's own panel path (scope, claims, policy, -- @vars, locked variables, limits); an input default the export binds must be a plain literal for an identifier that is not reserved; the SVG is sandboxed, CSV formula cells are neutralised |
/metrics (#765) leaks server internals or other viewers' activity |
Off unless options.metrics; its own bearer token (≥ 32 characters, constant-time compare), 401 without it; counts and timings only, with label values fixed by the server (a route name, a status class, a static reason), never a path, dashboard id, user or variable |
| A panel filters on a viewer-settable variable | Documented rule: filter only on __claim_*; -- @vars limits what viewers can set |
| One viewer's cached result served to another | Claims are part of the cache and single-flight key (both servers) |
| A result computed for other variable values served to a viewer | The key holds every variable the statement can depend on, worked out from the server's SQL and snapshot catalog, never from the request; whatever the analysis can't see through depends on every variable; claims and credential-locked variables always in full, never narrowed; the later of two spellings of a name wins, as in DuckDB, for the request's own variables and for a credential's locked ones; the server sets only the variables the key holds, so none of the rest can fail a shared execution for another request |
| One viewer cancels another's query | Supersession tickets are scoped to user + 128-bit page id |
A misconfigured auth serves without login |
A bad auth fails the start; there is no fallback to anonymous |
| Server reachable from the network without login | serve --bind beyond loopback without --auth prints a WARNING; so does the extension's start message for bind beyond loopback without auth (the default is loopback) |
| Log injection / personal data in logs | JSON-escaped lines; diagnostics on the same stderr escape control characters, and a URL with one is 400; variable values only with log_vars: "values"; the log file is 0600 and never opened through a symlink |
Many viewers fill the static server's --cache |
Capped at 1,024 pages / 64 MiB, expired pages purged |
| DNS rebinding, CSRF, SQL from the client | Unchanged: Host allowlist (421), same-origin POSTs, no SQL endpoint |
P3: a JWT with alg: none, or HS256 signed with the IdP's public key (algorithm confusion) |
Only asymmetric algorithms can be configured; the header's alg must be allowed before any key is used; oct JWKs are never loaded; each key verifies only its own type/curve (alg pinned when the JWK names one) |
A token signed by a key the attacker controls (jku, x5u, embedded jwk) |
Never followed: keys come only from the configured HTTPS key set |
Expired, not-yet-valid, foreign (iss/aud) or replayed-across-services tokens |
exp, iss, aud required; nbf/iat checked; leeway ≤ 5 min; iss exact; max_age_s optional |
Unknown kids to make the server hammer the IdP; a key set that can't be refreshed |
Refetch at most every 30 s; HTTPS only, no redirects, 10 s / 1 MiB caps; a set stale for 24 h is dropped (fail closed) |
A token supplies __claim_* names, SQL or control characters |
Variable names come only from the configuration; values are length- and control-character-checked and bound as typed literals |
| OIDC login CSRF / fixation, code interception, ID-token replay, open redirect after login | state (constant-time) and PKCE S256 in a signed HttpOnly cookie; nonce in the ID token; azp with several audiences; the state cookie is cleared on use; next must be a local path |
| A stolen or forged session cookie | Server-signed (HS256), HttpOnly; Secure; SameSite=Lax; __Host-; server-side expiry; logout revokes the id (durable and shared with revocation_file, else per replica); two session cookies → 401 |
| Someone claims a victim's e-mail at the IdP without verifying it (nOAuth, #115) | An email identity needs email_verified: true |
| A client's OIDC ID token replayed as an API bearer token | Refused unless accept_id_tokens; a jwt audience equal to the OIDC client_id fails the start |
A tampered or expired embed link; a link for one dashboard used on another; ?v.* or a panel request overriding the link's variables |
HMAC check in constant time; exp required and ≤ max_link_ttl_s; the link must name the dashboard; the page session is server-signed and scoped; locked variables replace the viewer's and are set after them (unit-tested order) |
A locked variable's ::INPUT default (the script-free server's own first-load bind, not a viewer-chosen value) overriding the embed link's locked value (#540) |
The default-bind is skipped entirely for a locked name, same as for a whitelisted -- @param (integration-tested) |
| A replayed embed link | Short max_link_ttl_s; one_time with jti (per process); documented: a link is a bearer credential until it expires |
| The host application mints server sessions (#114) | The embed link secret must differ from every other configured secret — both session secrets and the proxy's — or the start fails; a session claiming a longer life (exp - iat) than its method's session_ttl_s is refused |
| A leaked API key file; a guessed key; a revoked key still working | Only SHA-256 hashes of 256-bit keys; constant-time hash compare; the file is re-read on change (≤ 2 s); revoked/expired keys refused; a broken or group/world-writable file disables every key |
| Keys, tokens or codes in logs | Never logged; the audit log names key ids and session ids only (unit-tested) |
| A credential plus another to confuse the server | Exactly one credential counts per request, in a fixed order; an invalid one is refused, never skipped |
| Share links (#763): a share link reaching more than its dashboard | The share identity is scoped to its one dashboard; /, other dashboards and the API without a page session are 401; the login cookie's Path is that dashboard's, and it is checked against the dashboard it was issued for |
| Guessing a shared dashboard's password | 10 failures per address / 100 per dashboard per 15 min, then 429; PBKDF2-HMAC-SHA256, 600,000 iterations; at most 4 checks at a time; only the hash is configured |
| Locking everyone out of a shared dashboard on purpose (100 wrong passwords) | Accepted trade-off against distributed guessing: new password logins for that dashboard wait up to 15 minutes; viewers already signed in keep their cookie; public dashboards and other logins are unaffected. Use a generated password (--generate) and a reverse-proxy limit in front |
Which dashboards have a password (a fast 404 vs. a slow check) |
Not secret: a dashboard's page already says it needs one |
| The share identity used to write or pose as someone | share:<id> is reserved (no other method may claim it) and never submits or saves |
| An open redirect or reflected markup through the password form | next must be the dashboard's own page; every value on the page is HTML-escaped; the page is no-store |
| A password in logs | Never logged (unit-tested and e2e-tested) |
Out of scope for P1 and P3: on its own, a login relies on the dashboard
author writing the claim filter into every panel;
P2 policies enforce it
regardless of the panel SQL. Not in P3: per-tenant snapshots, rate limiting of
failed logins other than share-link passwords (put it in the reverse proxy), refresh tokens / silent re-login
(a session ends at session_ttl_s).
What can never enforce access: a static HTML export or the browser / DuckDB-Wasm demo (the data is in the client, whoever opens it can read all of it), and a MotherDuck token (it grants the whole database). Only the locked server (A) and the static render server (B) keep data on the server.
With P1 every panel has to filter on the claims itself, and one forgotten
WHERE shows every row. A policy moves the rule out of the panels: the
locked server (A) rewrites every dashboard statement so that it can only read
tables through per-viewer views, and refuses to start when a statement could
get around them.
{
"tables": {
"sales": {
"rows": "region IN (SELECT region FROM entitlements WHERE viewer = getvariable('__claim_user')) OR list_contains(getvariable('__claim_groups'), 'admins')"
},
"employees": {
"rows": "getvariable('__claim_tenant') = tenant",
"columns": {
"salary": {"allow_groups": ["hr"], "else": "null"},
"email": {"allow_groups": ["hr", "support"], "else": "mask"},
"name": {"allow_groups": ["hr"], "else": "hash"},
"ssn": {"allow_users": ["payroll@example.com"], "else": "deny"}
}
},
"ref.regions": {"rows": true}
}
}Pass the path of the policy, or put it in policy.json next to the dashboards:
anofox_serve_dashboards('dashboards', 8095, '{"auth": {…}, "policy": "/etc/anofox/policy.json"}').
A policy.json in the dashboard folder is enforced even without the option, so
forgetting the option can't serve every row. Keep the policy outside the
dashboard folder when the people who write dashboards should not decide who
sees what: with options.policy a missing or broken file stops the start.
With auth and no policy found (e.g. a policy.json deleted from the
folder) the server refuses to start unless "policy": "none" says that the
panels filter on the claims themselves. The start message says access policy on N table(s); with a policy but no auth it warns that every viewer is
anonymous (claims unset, so claim-based row filters return nothing).
Under a policy, a viewer whose panel fails gets a generic message ("this panel could not be shown"); the DuckDB error, which might quote a value, goes to the server log only.
| Key | Meaning |
|---|---|
tables |
{"<table>" or "<schema>.<table>": rule} — tables and views of the snapshot's default database (the one the session USEs). Every table a dashboard reads needs a rule; any other table is refused. |
tables.*.rows |
Required. A SQL condition over the table's columns that a row must meet, or true for every row. It may read the viewer only through getvariable('__claim_…') with a literal name (a viewer variable is refused). It may use other tables (e.g. an entitlement table): those are read directly, without their own policy, and the panels still can't read them unless they have a rule too. It must be one condition: text that ends the WHERE (… ) UNION SELECT …) is refused. |
tables.*.columns |
{"<column>": "deny" | "null" | "mask" | "hash"} for everyone, or {"allow_groups": [...], "allow_users": [...], "else": "deny" | "null" | "mask" | "hash"} (default else: null). Viewers in an allowed group (__claim_groups) or with an allowed user name (__claim_user) see the value. Columns not listed are visible. |
table_functions |
File readers the dashboards may call (read_parquet, read_csv, read_json, … glob). Off by default. Files have no row or column policy (DuckDB still confines them to options.data). Nothing else can be allowed. |
functions |
Extra scalar / aggregate functions the dashboards may call — an extension's (st_area, …), after you reviewed that they only compute on their arguments. A function the reviewed list denies can't be added. |
The hash mask's key is random per server start; set
"policy_key_env": "ANOFOX_POLICY_KEY" (the name of an environment variable
holding ≥ 32 characters, e.g. openssl rand -hex 32) in the server options
to keep hashes stable across restarts.
Unknown keys are errors. The policy is checked against the snapshot at start
and at every refresh: a table or column it names that doesn't exist, a row
filter that doesn't parse or bind, or a relation named __anofox… stops the
start (a failing refresh keeps the previous snapshot in service,
refresh_failed: true in /healthz).
| Column rule | The viewer gets |
|---|---|
deny |
no column: it is not in the view (SELECT * leaves it out; a panel naming it fails for this viewer — lint below) |
null |
NULL of the column's type: the panel keeps working |
mask |
'****' (NULL stays NULL) |
hash |
16 hex digits of HMAC-SHA256(key, column ‖ value): equal values in one column stay equal, so grouping and count(DISTINCT …) work, but the value can't be looked up, and the same value hashes differently in another column. The server computes it in its own function (__anofox_policy_hash), so the key is never in SQL, plans, errors or logs. Random per server start unless policy_key_env is set |
- At start (and per refresh), once per statement. DuckDB parses the
statement (
json_serialize_sql). Every table reference becomestemp.main.__anofox_rls_<i>(with the original name as alias, sot.colstill works); CTE names are renamed to__anofox_cte_<n>, so a name the rewrite takes for a CTE can only ever bind to that CTE. DuckDB prints the result (json_deserialize_sql), which is parsed again and verified: it may reference only those views, the dashboard's own temp objects and the renamed CTEs. The browser still shows the dashboard's original SQL; the server runs only the rewritten one. - Per request, on the request's private connection, after the claims are
set:
CREATE TEMP VIEW __anofox_rls_<i> AS SELECT * EXCLUDE (denied) REPLACE (masked) FROM (SELECT * FROM <db>.<schema>.<table> WHERE <rows>). The column decision uses the viewer's claims; the row filter reads them from the session variables. A claim value is never spliced into SQL text. ::PAGEDrequests (rows, count, stats, profile, distinct, filters) wrap the rewritten panel, so they see only the viewer's rows and masked values. The result cache and single-flight key include the claims (P1).
Fail closed. A dashboard statement is refused, and the server does not start (the error names the dashboard and statement), when it:
- reads a table or view without a rule, including
information_schema.*,pg_catalog.*, a file path (FROM 'x.csv') and a view whose body reads other tables; - names a database (
snap.main.sales,temp.main.__anofox_rls_0); - calls a table function other than
range,generate_series,unnestand the policy'stable_functions— soquery(),query_table(),json_execute_serialized_sql(), theduckdb_*()/pragma_*()catalog functions,sql_auto_complete(), table macros and file readers; - calls a user macro whose body reads a table, calls a table function or
calls a function or macro the policy refuses; calls a user macro without
passing every argument (a parameter's default isn't in the catalog, so it
can't be checked); calls a user macro in a row filter. A scalar macro whose
body passes these checks (
CASE, arithmetic,getvariable(),current_date, other such macros) may be called (#1216); - calls a function that is not on the allowlist
(
src/host/policy_functions.txt: every function of the pinned DuckDB 1.5.6, classifiedallowordeny) or in the policy'sfunctions. Denied: the functions that read the catalog, statistics, settings or a SQL text of their own, outside the views —json_serialize_plan(it binds and optimizes any SQL string against the raw tables; its plans would leak min/max statistics and the view definitions),stats,json_serialize_sql,current_setting,current_query,currval,nextval,getenv, thepg_*/has_*_privilegecatalog macros, … A function the list doesn't know (a newer DuckDB, a loaded extension) is refused; a test fails when the pinned DuckDB has an unclassified function; - uses time travel (
AT (VERSION => …)),SHOW TABLESorDESCRIBE/SUMMARIZEof a table without a rule; - is not a query,
CREATE [OR REPLACE] TEMP TABLE|VIEW <name> AS <query>orSET VARIABLE <name> = <expr>(whose query / expression is rewritten too):CREATE MACRO,ATTACH,COPY,SET,PIVOT …statements (useFROM t PIVOT (…)), … are refused, as is a setup statement that sets a__claim_*variable or creates an object named__anofox….
CTEs, subqueries (in FROM, SELECT, WHERE, IN, EXISTS), joins
(lateral, positional, ASOF), set operations, recursive CTEs, PIVOT in FROM,
unnest of a subquery, DESCRIBE SELECT … and the dashboard's own temp tables
all work, and all read the viewer's views. A viewer request that sets a
__claim_* or __anofox… variable is 400.
Lint before serving. dashboard --check dash.sql --db snapshot.duckdb --policy policy.json reports what the server would refuse
(policy/refused), panels that use a column some viewers can't see
(policy/denied-column: a warning, an error when nobody may see it — the
panel then always fails), masked columns (policy/masked-column, a note)
and inputs whose options come from a table with a row filter while panels
on tables without one read their variable (policy/input-options-restricted,
#1217: those panels' numbers then change per viewer, with each viewer's
default — take the options from an unrestricted table).
It uses the server's classifier and function list; it runs the duckdb CLI
on PATH to parse, and warns (policy/duckdb-version) when that is not the
pinned 1.5.6. The server checks again at start and fails closed either way.
duckext/scripts/policy-key-e2e.sh <extension> runs a locked server with a
known hash key and checks that the key is on no reachable surface (panel
results and errors, ::PAGED profiles, the page, /healthz, stderr, the
request log), that the served hash is the specified HMAC, and that SQL which
could show it (duckdb_views(), current_query(), json_serialize_plan,
current_setting) and auth without a policy refuse to start.
| Threat | Mitigation |
|---|---|
| A panel forgets the claim filter | The panel reads the policy's view, not the table |
A dashboard reads a table without a rule (directly, in a subquery, a CTE, a UNION arm, a lateral join, a SET VARIABLE, a temp table) |
Every table reference in every statement is rewritten or refused; refused = no start |
A CTE named like a table (WITH payroll AS (…)), or a table named like a CTE |
CTEs are renamed; a reference the rewrite takes for a CTE can only bind to that CTE, everything else goes through a view or is refused. A non-recursive CTE's own name inside its body is the table, as in DuckDB |
snapshot.main.t, temp.main.__anofox_rls_0, information_schema, duckdb_tables(), pragma_table_info() |
Database-qualified names and catalog functions are refused |
String-built SQL: query('SELECT … ' || getvariable('x')), query_table(…), json_execute_serialized_sql(…) |
Refused (table functions outside the allowlist) |
| A macro (or a built-in macro) whose body reads a table | Refused: a user macro is allowed only when its body (every overload) reads no table, calls no table function and only allowed functions and macros, and the call passes every argument, so no unchecked default runs (#1216); table macros, macros in row filters and CREATE MACRO in setup are refused |
| A view in the snapshot whose body reads a protected table | A view needs its own rule; the view's rule is what applies to it |
Setup overwrites the claims (SET VARIABLE __claim_groups = ['admins']) or the views |
Refused at start; views are created after the claims and before any dashboard SQL, and their names are reserved |
A viewer sets __claim_* / __anofox… (vars, ?v.*, @param) |
400 / ignored (P1) |
| A row filter reads a viewer-settable variable | Refused at start: a row filter may read only getvariable('__claim_…') |
Row filter text that ends the WHERE clause |
Refused: the filter must stay one condition |
A masked or denied column via ::PAGED filter / sort / stats / distinct / profile |
Paging wraps the rewritten panel; it sees NULL / **** / a hash, a denied column doesn't exist |
Guessing a hashed value (dictionary attack on md5(email)) |
HMAC-SHA256 with a server key and the column's name, computed in Rust: the key never appears in SQL, plans, errors or logs |
Probing tables, statistics or the views' SQL through json_serialize_plan('…'), stats(col), current_setting, current_query (#105) |
Functions are allowlisted: those are deny, and anything not classified is refused |
| An error message quotes a value the viewer may not see | Under a policy viewers get a generic error; the details go to the log |
A dashboard author deletes policy.json from the dashboard folder |
With auth, no policy refuses the start unless "policy": "none"; keep the policy outside the folder (options.policy: a missing file stops the start) |
| One viewer's cached result served to another | Claims are part of the cache and single-flight key (P1) |
| A result computed for other variable values served to a viewer | The key holds every variable the statement can depend on, worked out from the server's SQL and snapshot catalog, never from the request; whatever the analysis can't see through depends on every variable; claims and credential-locked variables always in full, never narrowed; the later of two spellings of a name wins, as in DuckDB, for the request's own variables and for a credential's locked ones; the server sets only the variables the key holds, so none of the rest can fail a shared execution for another request |
| A refresh brings a renamed table or column | The policy is re-checked; the refresh fails and the previous snapshot stays |
| A rewrite bug lets a table through | The rewritten SQL is parsed again and verified against an allowlist of names; a mismatch stops the start |
Limits. Policies cover the locked server (A) only: the static render
server serve --dashboards (B) has no policies (filter in the panels, P1
style), and a static HTML export or the browser / DuckDB-Wasm demo can never
enforce rows or columns (the data is in the client). Files in options.data
read through allowed table_functions have no row or column policy. A rule
on a view applies to the view's output; the tables it reads are protected only
where panels read them directly. Column rules decide by user and group;
other claims (__claim_tenant, …) can drive row filters only. hash is
pseudonymisation, not encryption: a viewer who knows a value and sees it next
to its hash elsewhere can match them.
Status: prototype, not yet security-reviewed. options.source builds (part
of) a locked server's snapshot from a live DuckDB 2.0 Quack server
instead of (or alongside) the local session — serving data that lives on
another DuckDB 2.0 process, over Quack's own remote-query protocol. It needs
a DuckDB 2.0 host for the extension itself (Quack is a 2.0 feature); the
duckext/ Rust build runs unchanged, csrc/ is not involved.
SELECT anofox_serve_dashboards('dashboards', 8095, '{
"source": {
"uri": "quack:warehouse.internal:9494",
"token_file": "/etc/anofox/quack-token",
"as": "warehouse",
"schemas": ["sales"],
"views": "materialize",
"timeout_s": 120
}
}');source key |
Default | Meaning |
|---|---|---|
uri |
(required) | quack:host:port (quack:// is rejected with a hint) |
token_env / token_file |
exactly one required | Where the source's auth token comes from; re-read fresh on every build, never cached. Prefer token_file (0600) — token_env is readable by any SQL that runs in the host session before the lock |
token |
refused | A literal token in the SQL would end up in shell history and query logs |
as |
"source" |
The database name the copy is attached under; the default database unless options.search_path is set; a clash with another attached database refuses to start. With an access policy, this silently changes which database a policy's table names resolve against (a policy always resolves against the default database) — adding a source to a dashboard that already has a policy.json can make the policy's own (local) tables unreachable by their unqualified names. This fails closed (a database-qualified name is refused under a policy), but double-check options.search_path or the policy's table names after adding a source (security review I3) |
schemas |
every schema the source exposes | Restricts the copy; anything else the source exposes is dropped from the snapshot again, never served |
views |
"materialize" |
"materialize": copy a remote view's current rows into a table (its definition is not replayed — Quack exposes no view DDL to replay, only query results). "skip": leave it out, with a warning |
timeout_s |
600 |
A deadline for the whole build (schema + every table + every materialised view); the caller never waits longer than timeout_s plus a 5s grace, even if LOAD/ATTACH/teardown hang (see "Timeout and cancel") |
max_rows |
50,000,000 |
Per-table row budget, checked before copying each table — a hostile or oversized source fails the build instead of filling the snapshot |
max_bytes |
10 GiB | Cumulative snapshot-file size budget, checked after each table/view |
tls.fingerprint |
— | Reserved for a non-local source (open question below: not enforced by this prototype) |
How the build works. Quack never enters the serving instance or the
user's session, and the build never holds the host session's connection
(ctx.conn) — it runs before that lock is taken, so a stuck source can
never stall another locked server sharing the same host database, the
authoring console, or a new anofox_serve_dashboards call (security review
M1). Per build, a throwaway staging DuckDB instance (extension
autoload/autoinstall off), on its own detached thread, does the work: LOAD quack; a CREATE TEMPORARY SECRET (TYPE quack, TOKEN …) — never
ATTACH … (TOKEN …), which would leak the token into
duckdb_databases().options; ATTACH '<uri>' AS …; attach the new
snapshot file READ_WRITE; one BEGIN … COMMIT around one CREATE TABLE … AS SELECT * per table (never COPY FROM DATABASE … (SCHEMA), which would
replay the source's DDL — see "Generated columns" below) and one per
materialised view; DETACH both attachments and drop the secret. The
resulting file then goes through the existing READ_ONLY +
enable_external_access = false + lock_configuration = true path
unchanged — the same path a local database takes. The serving snapshot
itself never loads quack: a dashboard's -- @load quack, options.load,
or the live session already having it loaded are all refused at startup
(the 'quack' extension may not be loaded into a locked server).
Generated columns (security review L1). COPY FROM DATABASE … (SCHEMA)
would replay the source's DDL verbatim, including a generated column's
expression — DuckDB evaluates that lazily, on every read, so replayed into
the serving instance it would run there, past any access policy's
policy_functions.txt denylist (the policy only ever sees a panel calling a
denied function directly, never a generated column doing so on its behalf).
CREATE TABLE … AS SELECT * sidesteps this: it materialises every column's
current value, generated or not, so the serving instance never evaluates a
source-chosen expression. The trade-off: foreign keys, indexes, macros,
sequences, primary keys and NOT NULL are not carried over (irrelevant
for a READ_ONLY snapshot — nothing writes to it — but worth knowing if a
dashboard's SQL relies on a PRIMARY KEY existing). Nested types (LIST,
STRUCT, MAP, ENUM, …) still survive, since CTAS copies their values
like any other column's.
Refresh and failure. The startup build must succeed — fail closed, like
every other snapshot, and under the same bounded deadline as a refresh (no
special-casing: a hung source can't hang startup indefinitely either).
After that, a Quack source build runs through the existing refresh_s /
anofox_serve_refresh path (Current::rebuild, single-flight): a failed
refresh leaves the last good snapshot in service, same as any other refresh
failure. /healthz gains source_ok (did the last build succeed, and is
no build currently stuck past its deadline), consecutive_failures (resets
to 0 on any success) and build_overdue (a build the caller gave up
waiting on is still running in the background) — but only when
options.source is configured, and as numbers/booleans only: the source's
URI, its token env/file name and any error text never appear there (they go
to the server's own stderr, as usual).
Timeout and cancel (security review M1). The whole build — LOAD,
ATTACH, the copy and teardown, not only the data copy — runs on a
dedicated thread; the caller waits on a channel for at most timeout_s plus
a 5s grace, whether or not the remote side ever answers. If that budget
runs out, the caller gives up: the build counts as failed (source_ok: false, consecutive_failures incremented) and the thread is left running
in the background (build_overdue: true) rather than blocking anything —
DuckDB has no way to abort a stuck network wait from the outside, and the
remote side may still be the one holding things up. At most one
orphaned build per server is tolerated locally (while build_overdue is
set, a new attempt on that server — another refresh, or the next
refresh_s tick — fails fast instead of piling up threads; the orphaned
thread clears it for itself whenever it finally returns), and at most
two, process-wide, across every locked server sharing this process
(security review R2): once that many builds are running or abandoned
anywhere in the process, a further attempt on any server is refused
immediately with a clear error, instead of leaking another staging
instance's threads without bound. This is a process-wide resource cap, not
a per-server one — two stuck sources are enough to pause source
refreshes for every locked server in the process, not just their own:
existing snapshots keep serving (an outage-free degradation, not a
failure), but every affected server's data goes stale and shows
source_ok: false until one of the stuck builds finally returns (at its
own deadline) and frees a slot. Independently of the deadline, a watchdog thread on a
second staging connection (the first is busy running the copy) also
reacts to anofox_serve_stop being called on this server: cancelling the
server cancels a build in flight immediately (there is no separate per-build
cancel flag to race against the server's own stop signal — I2). When it
fires, the watchdog runs quack_cancel(catalog, quack_connection_id(alias))
from that second connection, then duckdb_interrupts the first —
interrupting the client's own connection does not, by itself, stop a
query already running on the remote side, so the watchdog always tries the
remote cancel first. That cancel can only reach a remote operation that has
actually started (an ATTACH that never completes — e.g. a source that
accepts a connection and never answers — has no cancellable handle yet, so
only the outer deadline above ever un-wedges the caller in that case; the
thread itself may still be stuck).
anofox_serve_stop never waits indefinitely on a stuck refresh_s build
either: that one thread gets a short, fixed 5s join budget, with anything
still running past it left to finish on its own, so stopping a server is
never itself turned into an outage by an unresponsive source. The HTTP
request-handling workers are a separate matter and are joined in full
(security review C1): each one handles at most one request at a time, and
that request is already bounded on its own (a locked server's own
timeout_ms cancels a running panel query), so there is no reason to cut
that join short — doing so previously let anofox_serve_stop report
success while a legitimate, still in-flight request kept the port bound
underneath it for however long that request had left to run.
Threat model delta — the review this prototype still needs:
- The host process holds a credential with full SQL access to the
source's session for the duration of a build: Quack has no server-side
read-only mode, and a client's
READ_ONLYintent isn't enforced by the protocol. Mitigations already in place: the token lives only in the throwaway staging instance; a temporary secret, neverATTACH … (TOKEN …); redaction on every error on the way out; the serving instance itself never loadsquack(enforced at startup, not just byenable_external_access— belt and suspenders, since even a quack-loaded-but-locked instance refuses every quack call too, "file system operations are disabled"). token_envis readable by any SQL that runs in the host session before the server locks it down (getenv(name));token_fileis not — usetoken_filefor anything that isn't a throwaway test. Buttoken_fileis only as safe as the process it's read from: the authoring console's/query(anofox_serve(port)) runs on this same host session, which is unlocked SQL, andread_text('<token_file>')works there exactly asgetenvwould — so anyone who can reach that console (loopback, token- and Origin-guarded, but still a live, full-SQL endpoint) can read the token either way (security review L2). Run a source-backed locked server in a process that does not also runanofox_serveauthoring, and make the token file0600, owned by the service user. This is a process-separation concern, not atoken_filevs.token_envone — moving totoken_filealone does not close it.- A source can feed arbitrary schemas and data into the snapshot:
options.source.schemasrestricts what is copied, but a reviewer must confirm the materialised names and types can't get aroundpolicy_functions.txtor the access-policy rewrites (#49) — a policy resolves names in the snapshot's catalog, which now includes whatever the source chose to call its tables. - Holding the token also lets the same credential cancel any other
client's query on the source (
quack_cancelhas no authorization scoping beyond the token). A least-privilege Quack server, or an authorization hook upstream of it, is recommended — this prototype doesn't add one. - A non-local source needs a TLS fingerprint or a proxy in front of it;
this prototype does not enforce
tls.fingerprint(see the open question). - The live session already having
quackloaded, a dashboard's-- @load quack, andoptions.load: ["quack"]are all refused at startup — a reviewer should still re-check this denylist whenever extension loading changes.
Open questions (not resolved by this prototype):
- Replay a remote view's/macro's DDL instead of materialising it, once Quack exposes one?
- A
max_stale_ssetting that answers503instead of serving data older than that, given a Quack source can go stale for longer than a typicalrefresh_s? - Is
tls.fingerprintenough for a non-local source, or should the prototype require a TLS-terminating proxy instead and refuse a bare non-loopbackquack:URI? - Incremental refresh — Quack has no change-tracking today, so every refresh re-copies every row.
- Does a 1.5.x-built host, not just 2.0, ever need to talk to a Quack server? (Not supported here; the prototype requires a 2.0 host.)
- What
heartbeat_timeout(aquack_queryparameter this prototype does not set) is appropriate for a production deployment?
A dashboard's images come from the dashboard itself: a data:image/… URI, an
https: URL, or a relative path under the dashboard folder's own assets/
(PR B: GET /d/<id>/assets/<rest>, below). img-src already allows 'self' data: https: (page_csp, host/serving.rs) for ::LOGO/::HEADER_IMAGE;
::IMAGE and Markdown images reuse that, not a wider allowance — neither PR
changes that CSP directive.
Only <dashboards dir>/assets/, never the rest of the dashboards folder
(.sql, policy.json, blueprint.json): the route is computed once at
startup (canonicalize(<dir>/assets)), None when there is no such folder
— every request then 404s.
- Same login as the dashboard page; scope is checked on
id, not on which file. This route is not inauth.public_asset: every request goes through the server's usualauthenticate()first (401 without a valid credential, same as/d/<id>itself), and anauth-scoped credential (an embed link, an API key) must nameidin its own scope (403, same as the page). Butassets/is per folder, not per dashboard: the scope check only gates which<id>a credential's own/d/<id>/assets/…URL may use — it does not, and cannot, know which dashboard's script actually references which file. A credential scoped to dashboardAcan fetch every file under the sharedassets/folder as/d/A/assets/<anything>, including an image onlyB's script uses. That is a reasonable model (an image belongs to the folder it sits in, not to the one dashboard that happens to reference it today), but it means anyone who may open any dashboard here can read every file inassets/— keep an image that only some viewers may see in a separate dashboards folder (a separateanofox_serve_dashboardscall, or a separate server) from one everyone may see, rather than relying on per-dashboard scoping to hide it. - Containment.
restis percent-decoded once, then refused (404) on: empty; over 512 bytes; a\, NUL or other control character; an empty,.or..segment; a segment starting with.. The resolved path (canonicalize(assets_root.join(rest))) muststarts_with(assets_root)— this also blocks a symlink insideassets/that points outside it, since canonicalizing follows the symlink to its real target before the containment check runs. - Extension allow-list, then a real magic-byte check. The extension
must be
png/jpg/jpeg/gif/webp/svg(case-insensitive) — checked before any filesystem access, so a request can't even probe for a non-image file's existence through this route. The file's own bytes are then sniffed (host::app_brand::sniff_image, the same signatures as::LOGO's own inlining) for theContent-Typeactually sent — not trusted from the extension — so a.sql/.jsonfile renamed.png(right extension, wrong real type) is refused too (src/image.rs::read_asset, shared with the CLI's/--site's own readers ofassets/). - Size cap.
options.max_asset_bytes(bytes, default 5 MiB; the clamp is 64 MiB, and it's additionally clamped tomax_inflight_mbat parse time — an asset cap above the whole server's in-flight budget could never be honoured anyway, and would otherwise 503 every asset request with nothing at startup saying why) — checked from the file's ownfstatbefore reading it, and again on what is actually read (so a FIFO or a race can't lie about its reported size), reported in/healthz'slimitsfor a signed-in caller. Held against the samemax_inflight_mbbudget a panel result is:min(the file's real size, max_asset_bytes)perGETin flight (not a pessimisticmax_asset_bytesregardless of the file's real size), or just the 4 KiB sniffing prefix perHEAD— concurrent asset requests can't grow memory use past that shared cap either, and a page full of small icons no longer pays for the full cap each. - Response headers:
X-Content-Type-Options: nosniff;Content-Security-Policy: default-src 'none'; style-src 'unsafe-inline'; sandbox(neutralises an SVG opened as a top-level document instead of inside an<img>— it already never runs a script either way, see below, but this is belt-and-braces for a viewer who opens the asset URL directly);Cache-Control: private, max-age=300(ormax-age=60withauthset — a shorter lifetime so a cached image doesn't keep answering long after a logout or a revoked credential; stillprivate, notno-store, since the browser's own cache is fine to use meanwhile);Cross-Origin-Resource-Policy: same-origin. - No snapshot. The file is read fresh on every request — an edited or newly added asset shows without a server refresh.
GETandHEADonly.POST(and any other method) is405, the same as every other route here.HEAD'sContent-Lengthis the file's real size (anfstat, not a prior read) — it agrees with whatGETwould send, without reading the whole file just to answerHEAD.- Embed links. A page's embed session travels as the
X-Anofox-Sessionheader, which an<img src>can't carry — the browser insteadfetches anassets/image with that header and shows it from ablob:URL (web/app.js). OIDC and JWT cookies need nothing special; an API key sent as anAuthorizationheader works the same way a page's own requests do.
--site copies <folder>/assets/ to <out>/assets/ at publish time,
through the same read_asset validation (extension allow-list,
containment, real magic-byte MIME) the locked server applies per request
— "what the server would serve" and "what the site publishes" can't drift
apart. The size cap is options.max_asset_bytes when the same --options
file passed to anofox_serve_dashboards sets one, falling back to the
locked server's own 5 MiB default otherwise — not a fixed --site-only
value, so a site built from a server's own options file can't refuse a
file that server was configured to serve. It refuses the whole publish
(not just skipping) on a symlink anywhere inside assets/ (including
assets/ itself), a file whose real content isn't one of the allowed
image types regardless of its extension, a file over the cap, or — since a
published static site has no server to send the asset route's own
sandboxing CSP header — an "active" SVG. That check parses the file as XML
(not a text scan: a namespace-prefixed <x:script>, a foreign-namespace
element needing no <foreignObject> wrapper at all, a DTD entity
expansion, and entity-encoded text all defeat a text scan but not a parser
that resolves namespaces and decodes entities first) and allows only a
fixed list of SVG elements, each in the SVG namespace; every attribute
unprefixed or in the XLink namespace; no on…= attribute; href/
xlink:href only a same-document #fragment or, on <image> only, a
data:image/(png|jpeg|gif|webp) payload. Beyond that, every attribute
value (not only style — a presentation attribute such as fill,
filter, clip-path, mask or any marker-*/cursor takes the same
CSS syntax style does, so it can fetch a URL exactly as style can) is
refused if it contains a backslash (a CSS escape, e.g. u\72l(, reads as
url( to a CSS parser but not to a literal substring scan), a url(…)
that isn't a #fragment, or image-set(/@import/src(/javascript:/
expression(. No <!DOCTYPE or processing instruction anywhere, either.
A dot-leading entry (.secret.png, .DS_Store, a stray .git/, …) is
silently skipped — not published, not a publish failure. If a static host
can be configured to add response headers, add X-Content-Type-Options: nosniff and a Content-Security-Policy: sandbox (or stricter) for
/assets/ there too, for the same belt-and-braces reason the locked route
sends them — publish-time refusal is the real guarantee, those headers are
defense in depth on top of it. dashboard file.sql out.html/--svg and
the script-free serve --dashboards page read assets/ the same way
(read_asset) but inline the result as a data: URI rather than serving a
route, since neither has a client that fetches one (nor, therefore, the
active-SVG check above — the static output never serves the SVG markup to
anyone, only its own pre-rendered static charts and whatever <image href> the browser's <img>-only trust model already applies to a data:
URI the same as any other accepted source).
The authoring builder (serve [db], loopback-only; anofox_serve(port, options)) has no dashboards folder at all (plan-514 decision 5) — unlike
--dashboards <dir>/anofox_serve_dashboards, there is no <dir>/assets/
to derive a route from, so a relative ::IMAGE/markdown source always drew
the alt-text placeholder while authoring, even once PR B shipped. `--assets
- Validated once at start, loudly. Unlike
<dashboards dir>/assets/(silentlyNonewhen missing — an author may just not have made one yet), this path was named on purpose: a symlinked root (including one named with a trailing slash or a trailing/.— review of #604 S5,symlink_metadataon such a path is forced to resolve through the link to confirm it's a directory, so the literal path is normalized before that check runs), a missing path, or a path that isn't a directory all refuse to start (exit 2 for the CLI; an error fromanofox_servefor the extension), not a silent "nothing served" (src/image.rs::validated_assets_root). The resolved, canonical path is logged/returned once.--assets /(or$HOME) is accepted — it's an opt-in on a loopback-only server, so this is a footgun, not a hole, but it does mean every readable image on disk is one request away for whoever holds the token. A hard link into the root (unlike a symlink) is served:canonicalizehas no way to see one, and making one needs write access to the root already. options.assetsadditionally needsenable_external_access(review of #604 S1). Unlike every SQL read on the live connection, this route reads files with plainstd::fs, bypassing that connection's ownenable_external_access/allowed_directoriessandbox entirely — someone running untrusted SQL in a session deliberately locked down that way could otherwise still getanofox_serve(port, {"assets": "/anything"})to read any image-typed file the process can, handed to whoever gets the token back. Refused outright instead: starting withoptions.assetsneedsenable_external_access = trueon that connection, and ifallowed_directoriesis non-empty, the root must canonicalize to a path inside at least one of them. The CLI's--assetsis unaffected — the person running it is the operator, not untrusted SQL. Checked once, atanofox_serve's own start — not on every request, and not again if the setting changes afterward (review of #604 R1): once a server withoptions.assetsis already running,SET enable_external_access = falseon that same connection does not stop it from continuing to answer/assets/<rest>(the token already went only to whoever started it, and no SQL function here lists a running server's own token back to anyone). Lock the session down — and, stronger still,SET lock_configuration = true— before callinganofox_servewith this option if that's the posture wanted for its whole lifetime, not after.- Same guard as every other authoring route.
GET/HEAD /assets/<rest>sits behind the same per-run token (cookie orX-Anofox-Token), loopbackHost, and same-origin checks as/query— there is no separate, weaker path to this route. Authoring has no per-dashboard scope to additionally check (it has no dashboards). - Same containment/extension/magic-byte/size rules and response headers
as the locked server's own route above — both go through
anofox_visualization::image's sharedopen_validated_asset/read_opened_asset/stat_opened_asset.Cache-Controlisprivate, max-age=60(the locked server's shorter,auth-configured lifetime — authoring has no logout to outlive, but an asset can change under an author's feet mid-session just as easily as the dashboard script itself). GET/HEADonly; no listing. Any other method on/assets/<rest>is405. With the option off,/assets/<rest>isn't a route at all, so it falls through to the same rule every other unknown path on this server already has:GETis404, andHEAD— along with every method butGET— is405(the static-file fallback only ever answersGET). Review of #604 R5: an earlier draft of this paragraph saidHEADwas404too; it is not, with or without the option.- Client. A relative
assets/…source resolves the same way in every mode (web/app.js::assetUrl's existing fallback: relative to the page's own URL, always/for the authoring builder) — with the option off, that request 404s and the viewer sees the alt-text placeholder, exactly as before #522; with it on, the same request now succeeds. No client-side flag or code path change was needed for this.
What is worth a reviewer's attention: an https: image loads
automatically, with no click, unlike ::LINK. If a ::MARKDOWN (or
::IMAGE) column is built from a text column that end users influence — a
support-ticket description, a free-text field — an attacker who controls
that text can point an <img> at any https: host, which reveals the
viewer's IP (and request timing) to that host. This is the same trust
::LINK already carries, just without the click gate. Recommend not
rendering untrusted/user-supplied text as ::MARKDOWN (or feeding it into
an ::IMAGE source); an author-written dashboard script is trusted the same
way its SQL already is.
Everything is drawn through an <img> (browser) or an SVG
<image href=…> (static output) — never inlined into the DOM, an
<object> or an <iframe> — so a browser runs no script and loads no
external resource from inside an SVG used as an image this way, even a
data:image/svg+xml one with embedded <script>. The source rules
(src/image.rs::src_ok, web/app.js::imageSrc()) refuse javascript:,
data:text/html and anything else outside the three allowed forms; neither
form admits raw HTML into the page (alt/caption text is always set with
textContent/setAttribute, or HTML-escaped in the Markdown path — see
DOCS.md's Images section for the lint codes that catch a bad source at
author time).
deployment.md covers deploying a locked server: one process
under systemd or in a container, TLS and auth at a reverse proxy (Caddy, nginx)
with the Host allowlist, resource limits, replicas behind a load balancer,
and sizing from the load test (scripts/load-test.mjs).
- Authentication + TLS for consumer-facing modes: terminate both at a reverse
proxy (nginx / Caddy / Cloudflare) in front of the server; bind the server to
loopback and let only the proxy reach it. Pass the identity on with
auth(above) when dashboards show different rows to different viewers. - Least privilege on the data: the snapshot contains everything in the
session's DuckDB databases, and every file in
options.datais readable. Serve from a session (or--db) that only holds the tables/views the dashboards need. - Variable values are not whitelisted in mode A: a viewer can set any
identifier-named variable (except
__claim_*;-- @varslimits the names) to any literal. Panels see them only throughgetvariable(), so write panel SQL that treats variables as untrusted values (they cannot change the query's structure), and never use one as an access filter. - Process isolation: run the server as an OS user without access to more than it needs.
- Retention and data-subject requests for
options.state(#517): nothing expires automatically. Back up the state file like any other data, decide a retention policy, and usedashboard state export|erase(above, under "Per-viewer state") for a data-subject export or erasure request — both run offline and refuse while a server still has the file open.
