From 86067d512433f0d383419389fb717741f3f1e8cf Mon Sep 17 00:00:00 2001 From: Lukas Date: Sat, 14 Nov 2026 01:09:38 +0100 Subject: [PATCH 1/5] refactor(server): transaction-aware variants of the org, key and reset mutators Add *_tx variants (create_org, update_org with name/quota/plan, set_org_quota/plan, delete_org, signup, create_password_reset, revoke_api_key) that run inside a caller's transaction so an operator action can write its audit row in the same BEGIN IMMEDIATE. The plain functions wrap them; put_org shares parse_job_quota. No behaviour change. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01TEvvb3zrZ3bLSGJbCBaEYX --- crates/server/src/server.rs | 22 +++-- crates/server/src/store.rs | 182 ++++++++++++++++++++++++++++++++++-- 2 files changed, 185 insertions(+), 19 deletions(-) diff --git a/crates/server/src/server.rs b/crates/server/src/server.rs index f215689..2506400 100644 --- a/crates/server/src/server.rs +++ b/crates/server/src/server.rs @@ -629,6 +629,16 @@ fn py_eq_int(v: &Value, i: i64) -> bool { /// The id in `` — the regex routes. `\d+` that does not fit an i64 is /// not a route (the Python crashed binding it), so it falls through to the 404. +/// A `job_quota` field: a non-negative integer, or null for unlimited. Shared by the root +/// `PUT /orgs/{id}` and the operator edit, so both reject the same values with the same text. +pub(crate) fn parse_job_quota(v: &Value) -> Result, &'static str> { + match v { + Value::Null => Ok(None), + Value::Number(n) if n.as_i64().is_some_and(|q| q >= 0) => Ok(n.as_i64()), + _ => Err("job_quota must be a non-negative integer or null"), + } +} + fn id_of(target: &str, prefix: &str, suffix: &str) -> Option { let d = target.strip_prefix(prefix)?.strip_suffix(suffix)?; if d.is_empty() || !d.bytes().all(|b| b.is_ascii_digit()) { @@ -2377,15 +2387,9 @@ impl Ctx<'_> { if p.kind != "root" { return Ok(jerr(403, "job_quota is set by the server operator")); } - let quota_n = match quota { - Value::Null => None, - Value::Number(n) if n.as_i64().is_some_and(|q| q >= 0) => n.as_i64(), - _ => { - return Ok(jerr( - 400, - "job_quota must be a non-negative integer or null", - )); - } + let quota_n = match parse_job_quota(quota) { + Ok(q) => q, + Err(msg) => return Ok(jerr(400, msg)), }; if !self.db(|c| store::set_org_quota(c, oid, quota_n))? { return Ok(not_found()); diff --git a/crates/server/src/store.rs b/crates/server/src/store.rs index f24fe3b..f12821c 100644 --- a/crates/server/src/store.rs +++ b/crates/server/src/store.rs @@ -565,15 +565,29 @@ pub fn month_start(now: f64) -> f64 { // string-building. Legacy DBs are entirely org_id=1, so org-1 callers see exactly what they saw // before. +// The `*_tx` variants run inside a transaction the caller owns (`begin_tx`), so an operator action +// can make its change and write its audit row under one `BEGIN IMMEDIATE`. The plain functions are +// `begin` + the `_tx` body + `commit`, nothing else. + +/// Open a write transaction (`BEGIN IMMEDIATE`) for a caller that composes several `*_tx` calls. +/// Dropping it without `commit` rolls back. +pub fn begin_tx(conn: &Connection) -> Result> { + begin(conn) +} + pub fn create_org(conn: &Connection, name: &str) -> Result { let tx = begin(conn)?; + let id = create_org_tx(&tx, name)?; + tx.commit()?; + Ok(id) +} + +pub fn create_org_tx(tx: &Transaction, name: &str) -> Result { tx.execute( "INSERT INTO orgs(name, created_at) VALUES(?,?)", params![name, crate::now()], )?; - let id = tx.last_insert_rowid(); - tx.commit()?; - Ok(id) + Ok(tx.last_insert_rowid()) } /// Orgs for the root listing. The Shopify webhook secret is reported as a flag, never echoed — @@ -661,6 +675,42 @@ pub fn set_org_quota(conn: &Connection, org_id: i64, quota: Option) -> Resu ) } +pub fn set_org_quota_tx(tx: &Transaction, org_id: i64, quota: Option) -> Result { + let n = tx.execute( + "UPDATE orgs SET job_quota=? WHERE id=?", + params![quota, org_id], + )?; + Ok(n == 1) +} + +/// What an operator edit may change on an org. `None` leaves a field alone; `job_quota: Some(None)` +/// sets unlimited. `plan` carries the catalogue id and the quota it grants, written together. +#[derive(Debug, Default, Clone, Copy)] +pub struct OrgUpdate<'a> { + pub name: Option<&'a str>, + pub job_quota: Option>, + pub plan: Option<(&'a str, Option)>, +} + +/// Apply every set field of `u` inside the caller's transaction. False if there is no such org. +/// Validation is the caller's job and happens before this runs, so nothing here rejects half-way. +/// An explicit `job_quota` is applied after the plan and so wins over the plan's quota. +pub fn update_org_tx(tx: &Transaction, org_id: i64, u: &OrgUpdate) -> Result { + if !org_exists(tx, org_id)? { + return Ok(false); + } + if let Some(name) = u.name { + tx.execute("UPDATE orgs SET name=? WHERE id=?", params![name, org_id])?; + } + if let Some((plan, quota)) = u.plan { + set_org_plan_tx(tx, org_id, plan, quota)?; + } + if let Some(quota) = u.job_quota { + set_org_quota_tx(tx, org_id, quota)?; + } + Ok(true) +} + /// Move an org onto a billing plan. The plan id is bookkeeping; its quota is what bites, and /// both are written in one UPDATE so they can never disagree. False if no such org. pub fn set_org_plan( @@ -670,11 +720,21 @@ pub fn set_org_plan( quota: Option, ) -> Result { let tx = begin(conn)?; + let ok = set_org_plan_tx(&tx, org_id, plan, quota)?; + tx.commit()?; + Ok(ok) +} + +pub fn set_org_plan_tx( + tx: &Transaction, + org_id: i64, + plan: &str, + quota: Option, +) -> Result { let n = tx.execute( "UPDATE orgs SET plan=?, job_quota=? WHERE id=?", params![plan, quota, org_id], )?; - tx.commit()?; Ok(n == 1) } @@ -726,6 +786,15 @@ pub fn truncate_wal_logged(conn: &Connection, what: &str) -> bool { /// key still enrolls there. pub fn delete_org(conn: &Connection, org_id: i64) -> Result { let tx = begin(conn)?; + let found = delete_org_tx(&tx, org_id)?; + if found { + tx.commit()?; + } + Ok(found) +} + +/// `delete_org` inside the caller's transaction; the caller commits (and drops it on `false`). +pub fn delete_org_tx(tx: &Transaction, org_id: i64) -> Result { if tx .query_row("SELECT 1 FROM orgs WHERE id=?", [org_id], |_| Ok(())) .optional()? @@ -754,7 +823,6 @@ pub fn delete_org(conn: &Connection, org_id: i64) -> Result { tx.execute(&format!("DELETE FROM {table} WHERE org_id=?"), [org_id])?; } tx.execute("DELETE FROM orgs WHERE id=?", [org_id])?; - tx.commit()?; Ok(true) } @@ -999,11 +1067,16 @@ pub fn list_api_keys(conn: &Connection, org_id: Option) -> Result) -> Result { let tx = begin(conn)?; + let ok = revoke_api_key_tx(&tx, key_id, org_id)?; + tx.commit()?; + Ok(ok) +} + +pub fn revoke_api_key_tx(tx: &Transaction, key_id: i64, org_id: Option) -> Result { let n = tx.execute( "UPDATE api_keys SET active=0 WHERE id=:kid AND (:org IS NULL OR org_id = :org)", named_params! {":kid": key_id, ":org": org_id}, )?; - tx.commit()?; Ok(n == 1) } @@ -1051,10 +1124,32 @@ pub fn signup( password_hash: &str, job_quota: Option, terms_version: Option<&str>, +) -> Result { + let tx = begin(conn)?; + let out = signup_tx( + &tx, + org_name, + email, + password_hash, + job_quota, + terms_version, + )?; + tx.commit()?; + Ok(out) +} + +/// `signup` inside the caller's transaction. Err(Conflict) leaves the half-made org for the +/// caller's rollback (drop the transaction without committing). +pub fn signup_tx( + tx: &Transaction, + org_name: &str, + email: &str, + password_hash: &str, + job_quota: Option, + terms_version: Option<&str>, ) -> Result { let now = crate::now(); let addr = normalize_email(email); - let tx = begin(conn)?; tx.execute( "INSERT INTO orgs(name, job_quota, created_at) VALUES(?,?,?)", params![org_name, job_quota, now], @@ -1071,7 +1166,6 @@ pub fn signup( params![org_id, user_id, version, now], )?; } - tx.commit()?; Ok(Signup { org_id, user_id }) } @@ -1116,16 +1210,27 @@ pub fn create_password_reset( token: &str, ttl_s: f64, now: Option, +) -> Result { + let tx = begin(conn)?; + let expires_at = create_password_reset_tx(&tx, user_id, token, ttl_s, now)?; + tx.commit()?; + Ok(expires_at) +} + +pub fn create_password_reset_tx( + tx: &Transaction, + user_id: i64, + token: &str, + ttl_s: f64, + now: Option, ) -> Result { let now = now.unwrap_or_else(crate::now); let expires_at = now + ttl_s; - let tx = begin(conn)?; tx.execute("DELETE FROM password_resets WHERE user_id=?", [user_id])?; tx.execute( "INSERT INTO password_resets(user_id, token_hash, created_at, expires_at) VALUES(?,?,?,?)", params![user_id, hash_key(token), now, expires_at], )?; - tx.commit()?; Ok(expires_at) } @@ -2860,6 +2965,63 @@ mod tests { ); } + // --- transaction-aware variants: compose with a caller's write, roll back with it ------------ + + #[test] + fn update_org_tx_applies_all_fields_and_rolls_back_with_the_caller() { + let conn = db(); + let oid = create_org(&conn, "acme").unwrap(); + let upd = OrgUpdate { + name: Some("acme 2"), + job_quota: Some(Some(7)), + plan: Some(("pro", Some(500))), + }; + let tx = begin_tx(&conn).unwrap(); + assert!(update_org_tx(&tx, oid, &upd).unwrap()); + drop(tx); // the caller's later step failed: nothing may stay + let o = get_org(&conn, oid).unwrap().unwrap(); + assert_eq!((o.name.as_str(), o.job_quota, o.plan), ("acme", None, None)); + + let tx = begin_tx(&conn).unwrap(); + assert!(update_org_tx(&tx, oid, &upd).unwrap()); + tx.commit().unwrap(); + let o = get_org(&conn, oid).unwrap().unwrap(); + assert_eq!(o.name, "acme 2"); + assert_eq!(o.plan.as_deref(), Some("pro")); + assert_eq!(o.job_quota, Some(7)); // the explicit quota wins over the plan's + + let tx = begin_tx(&conn).unwrap(); + assert!(!update_org_tx(&tx, 999_999, &upd).unwrap()); + } + + #[test] + fn delete_org_tx_leaves_the_commit_to_the_caller() { + let conn = db(); + let oid = create_org(&conn, "gone").unwrap(); + let tx = begin_tx(&conn).unwrap(); + assert!(delete_org_tx(&tx, oid).unwrap()); + drop(tx); + assert!(org_exists(&conn, oid).unwrap()); + let tx = begin_tx(&conn).unwrap(); + assert!(delete_org_tx(&tx, oid).unwrap()); + tx.commit().unwrap(); + assert!(!org_exists(&conn, oid).unwrap()); + let tx = begin_tx(&conn).unwrap(); + assert!(!delete_org_tx(&tx, oid).unwrap()); + } + + #[test] + fn signup_tx_rolls_back_the_org_when_the_email_is_taken() { + let conn = db(); + signup(&conn, "a", "x@example.com", "h", None, None).unwrap(); + let before = list_orgs(&conn).unwrap().len(); + let tx = begin_tx(&conn).unwrap(); + let r = signup_tx(&tx, "b", "x@example.com", "h", Some(5), None); + assert!(matches!(r, Err(StoreError::Conflict))); + drop(tx); + assert_eq!(list_orgs(&conn).unwrap().len(), before); + } + // --- multi-tenancy -------------------------------------------------------------------- #[test] From 9fab2a82a336f7781958629d4a52b9f2c924a82d Mon Sep 17 00:00:00 2001 From: Lukas Date: Sat, 14 Nov 2026 01:25:15 +0100 Subject: [PATCH 2/5] feat(server): operator gate, hosted mode and the operator audit log PRINTAPI_OPERATOR_TOKEN turns on a /operator/ API (404 everywhere while unset). The token is accepted only from a socket peer in PRINTAPI_OPERATOR_FROM (never X-Forwarded-For; Req gains a raw socket_peer), root is 401 there, and on every other route the token is stripped before session, key, Basic, CloudPRNT, agent or long-poll lookup and refused by enrollment_org even with open enrollment. With the token set, private URLs default to deny and fetches_per_org to 4. Every /operator/ response is no-store; the access log drops its query string. New operator_audit table (new table only) with GET /operator/audit (keyset paging by before_id), GET /operator/overview (features: [], cached 10 s, indexed queries via the new jobs_created index), docs/operator.md and the docs/server.md env rows. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01TEvvb3zrZ3bLSGJbCBaEYX --- README.md | 1 + crates/server/src/http.rs | 36 +- crates/server/src/main.rs | 163 +++++++- crates/server/src/server.rs | 72 +++- crates/server/src/server/operator.rs | 194 ++++++++++ crates/server/src/store.rs | 186 ++++++++- crates/server/tests/common/mod.rs | 7 + crates/server/tests/http_operator.rs | 552 +++++++++++++++++++++++++++ crates/server/tests/store_compat.rs | 80 ++++ docs/operator.md | 111 ++++++ docs/server.md | 6 +- 11 files changed, 1395 insertions(+), 13 deletions(-) create mode 100644 crates/server/src/server/operator.rs create mode 100644 crates/server/tests/http_operator.rs create mode 100644 docs/operator.md diff --git a/README.md b/README.md index 2b8b19e..5dd1013 100644 --- a/README.md +++ b/README.md @@ -185,6 +185,7 @@ sponsored by PrintNode.* | [Recipes](docs/recipes.md) | print from n8n, Zapier, Make, curl in one HTTP node | | [E-commerce](docs/ecommerce.md) | WooCommerce plugin, Shopify webhook, `POST /orders` | | [Billing](docs/billing.md) | plans, checkout links, the signed provider webhook, org deletion | +| [Operator API](docs/operator.md) | for a hosted deployment: a service token, the audit log and the overview a separate console reads | | [Migration](docs/migration.md) | upgrading from v2 (Python) to v3 (Rust): server, agents, changed defaults, rollback | | [Roadmap](docs/roadmap.md) | what shipped and what is next | diff --git a/crates/server/src/http.rs b/crates/server/src/http.rs index e287c9f..8e907b9 100644 --- a/crates/server/src/http.rs +++ b/crates/server/src/http.rs @@ -162,7 +162,14 @@ async fn respond( let mut close = false; let resp = if method == "GET" && target == "/agent/jobs" { // Python compared self.path, so "/agent/jobs?x=1" is not the long-poll. - long_poll(&ctx.state, bearer(&parts.headers)).await + let key = bearer(&parts.headers); + // The operator token is no agent key either: an empty key answers 401 at once. + let key = if server::is_operator_token(&ctx.state.cfg, key) { + "" + } else { + key + }; + long_poll(&ctx.state, key).await } else { let declared = parts .headers @@ -190,6 +197,7 @@ async fn respond( body, body_error, peer_ip: client.clone(), + socket_peer: peer.ip().to_string(), }; let (st, handler) = (ctx.state.clone(), ctx.handler); match tokio::task::spawn_blocking(move || handler(&st, &req)).await { @@ -442,6 +450,13 @@ fn access_log_line( version: &str, status: u16, ) -> String { + // The query of an `/operator/` request can name a customer (`q=` searches e-mail addresses), + // so it stays out of the log. + let target = if target.starts_with("/operator/") { + target.split('?').next().unwrap_or(target) + } else { + target + }; format!("{ip} - - [{when}] \"{method} {target} {version}\" {status} -") } @@ -558,6 +573,25 @@ mod tests { ); } + #[test] + fn operator_paths_are_logged_without_their_query_string() { + let line = access_log_line( + "10.0.0.7", + "31/Oct/2026 01:52:18", + "GET", + "/operator/orgs?q=alice%40shop.test&status=active", + "HTTP/1.1", + 200, + ); + assert_eq!( + line, + "10.0.0.7 - - [31/Oct/2026 01:52:18] \"GET /operator/orgs HTTP/1.1\" 200 -" + ); + // every other path keeps what it always logged + let line = access_log_line("10.0.0.7", "t", "GET", "/jobs?limit=5", "HTTP/1.1", 200); + assert!(line.contains("/jobs?limit=5"), "{line}"); + } + #[test] fn log_timestamp_has_python_shape() { let t = log_timestamp(); // 31/Oct/2026 01:52:18 diff --git a/crates/server/src/main.rs b/crates/server/src/main.rs index b4a55b9..875cb93 100644 --- a/crates/server/src/main.rs +++ b/crates/server/src/main.rs @@ -9,7 +9,10 @@ //! callback, and until queued jobs without a deadline are failed; their row goes after //! max(N, 7) days if it is from before this UTC month; unset or 0 keeps everything), PRINTAPI_TERMS_VERSION (set: `POST /signup` //! must accept that version of the terms), PRINTAPI_TERMS_URL (required with it), PRINTAPI_DPA_URL, -//! PRINTAPI_PRIVACY_URL (optional links, http(s) only), LOG_REQUESTS, SMTP_*. +//! PRINTAPI_PRIVACY_URL (optional links, http(s) only), PRINTAPI_OPERATOR_TOKEN (set: the +//! `/operator/` API is on, at least 32 characters, and hosted mode with it: private URLs denied and +//! 4 fetches per org unless set), PRINTAPI_OPERATOR_FROM (required with it: IPs or CIDRs the token is +//! accepted from), LOG_REQUESTS, SMTP_*. use printpapi_server::dispatch::{Destinations, HttpFetcher, OUTBOUND_IN_FLIGHT}; use printpapi_server::mail::{self, SmtpMailer}; use printpapi_server::server::{AppState, Config, Terms}; @@ -115,6 +118,39 @@ fn parse_terms( })) } +/// The operator token and the peers it is accepted from. Unset or blank: the operator API is off. +/// The token is at least 32 characters, never starts with `sess_` (a session's prefix, which the +/// credential lookup treats specially) and is not the root token. The peer list is required: a +/// token that works from anywhere is not what the operator API is for. +fn parse_operator( + token: &str, + from: &str, + root: &str, +) -> Result, String> { + let token = py_strip(token); + if token.is_empty() { + return Ok(None); + } + if token.chars().count() < 32 { + return Err("PRINTAPI_OPERATOR_TOKEN must be at least 32 characters".into()); + } + if token.starts_with("sess_") { + return Err("PRINTAPI_OPERATOR_TOKEN must not start with sess_".into()); + } + if token == root { + return Err("PRINTAPI_OPERATOR_TOKEN must differ from PRINTAPI_TOKEN".into()); + } + let from = printpapi_server::proxy::TrustedProxies::parse(from) + .map_err(|e| format!("PRINTAPI_OPERATOR_FROM: {e}"))?; + if from.is_empty() { + return Err( + "PRINTAPI_OPERATOR_FROM is required with PRINTAPI_OPERATOR_TOKEN (the console's address, e.g. 172.30.0.3)" + .into(), + ); + } + Ok(Some((token.to_string(), from))) +} + /// One stderr line per hosted-beta safeguard that is off while strangers can sign up. fn startup_warnings(cfg: &Config) -> Vec<&'static str> { let mut out = Vec::new(); @@ -137,6 +173,10 @@ fn startup_warnings(cfg: &Config) -> Vec<&'static str> { } fn config() -> Result<(Config, String, u16), String> { + config_from(&env) +} + +fn config_from(env: &dyn Fn(&str) -> Option) -> Result<(Config, String, u16), String> { let token = env("PRINTAPI_TOKEN").ok_or("PRINTAPI_TOKEN is required")?; if py_strip(&token).is_empty() { // An empty bootstrap token would compare-equal every missing Authorization header, @@ -173,11 +213,22 @@ fn config() -> Result<(Config, String, u16), String> { cfg.plans = billing::load_plans(&raw_plans).map_err(|e| e.to_string())?; cfg.billing_secret = env("PRINTAPI_BILLING_SECRET").filter(|s| !s.is_empty()); cfg.log_requests = env("LOG_REQUESTS").is_some_and(|s| !s.is_empty()); + if let Some((token, from)) = parse_operator( + &env("PRINTAPI_OPERATOR_TOKEN").unwrap_or_default(), + &env("PRINTAPI_OPERATOR_FROM").unwrap_or_default(), + &cfg.token, + )? { + cfg.operator_token = Some(token); + cfg.operator_from = from; + } + // Hosted mode comes with the operator token: strangers' jobs run here, so the safe defaults + // hold whatever signup says, fixed at startup (a later live setting never moves them). + let hosted = cfg.operator_token.is_some(); // Private destinations are refused by default exactly when strangers get accounts (open - // signup); a self-hosted box keeps fetching from its LAN. + // signup, or hosted mode); a self-hosted box keeps fetching from its LAN. let private = env("PRINTAPI_PRIVATE_URLS").unwrap_or_default(); cfg.destinations = match py_strip(&private) { - "" if cfg.signup_open => Destinations::PublicOnly, + "" if cfg.signup_open || hosted => Destinations::PublicOnly, "" | "allow" => Destinations::Any, "deny" => Destinations::PublicOnly, other => { @@ -188,6 +239,9 @@ fn config() -> Result<(Config, String, u16), String> { }; cfg.fetches_per_org = parse_fetch_cap(&env("PRINTAPI_FETCHES_PER_ORG").unwrap_or_default()) .map_err(|e| format!("PRINTAPI_FETCHES_PER_ORG: {e}"))?; + if hosted && cfg.fetches_per_org.is_none() { + cfg.fetches_per_org = Some(printpapi_server::server::MAX_FETCHES_PER_ORG); + } cfg.trusted_proxies = printpapi_server::proxy::TrustedProxies::parse( &env("PRINTAPI_TRUSTED_PROXIES").unwrap_or_default(), ) @@ -236,6 +290,9 @@ fn run() -> Result<(), String> { for line in startup_warnings(&cfg) { eprintln!("{line}"); } + if cfg.operator_token.is_some() { + eprintln!("operator API on (hosted mode: private URLs denied unless allowed explicitly)"); + } let db = Db::open(&db_path).map_err(|e| format!("cannot open database {db_path:?}: {e}"))?; let state = Arc::new(AppState::new( cfg, @@ -354,3 +411,103 @@ mod terms_tests { assert!(parse_terms("v1", "", "", "").is_err()); } } + +#[cfg(test)] +mod operator_tests { + use super::config_from; + use printpapi_server::dispatch::Destinations; + use printpapi_server::server::Config; + + const ROOT: &str = "root-token"; + const OP: &str = "operator-token-0123456789abcdef-xyz"; + + fn cfg(extra: &[(&str, &str)]) -> Result { + let mut vars: Vec<(String, String)> = vec![("PRINTAPI_TOKEN".into(), ROOT.into())]; + vars.extend(extra.iter().map(|(k, v)| (k.to_string(), v.to_string()))); + config_from(&|k| vars.iter().rfind(|(n, _)| n == k).map(|(_, v)| v.clone())) + .map(|(c, _, _)| c) + } + + /// The operator variables plus `extra`; an entry of `extra` replaces the default of its name. + fn with_op(extra: &[(&str, &str)]) -> Result { + let mut v = vec![ + ("PRINTAPI_OPERATOR_TOKEN", OP), + ("PRINTAPI_OPERATOR_FROM", "10.9.0.2"), + ]; + for (k, val) in extra { + v.retain(|(n, _)| n != k); + v.push((k, val)); + } + cfg(&v) + } + + #[test] + fn unset_the_operator_api_is_off_and_nothing_else_changes() { + let c = cfg(&[]).unwrap(); + assert!(c.operator_token.is_none()); + assert_eq!(c.destinations, Destinations::Any); + assert_eq!(c.fetches_per_org, None); + } + + #[test] + fn a_token_needs_from() { + let e = cfg(&[("PRINTAPI_OPERATOR_TOKEN", OP)]).unwrap_err(); + assert!(e.contains("PRINTAPI_OPERATOR_FROM"), "{e}"); + let e = cfg(&[ + ("PRINTAPI_OPERATOR_TOKEN", OP), + ("PRINTAPI_OPERATOR_FROM", " "), + ]) + .unwrap_err(); + assert!(e.contains("PRINTAPI_OPERATOR_FROM"), "{e}"); + let c = with_op(&[]).unwrap(); + assert_eq!(c.operator_token.as_deref(), Some(OP)); + assert!(!c.operator_from.is_empty()); + } + + #[test] + fn the_token_must_be_long_and_not_look_like_a_session_or_the_root_token() { + let short = "a".repeat(31); + let e = with_op(&[("PRINTAPI_OPERATOR_TOKEN", &short)]).unwrap_err(); + assert!(e.contains("PRINTAPI_OPERATOR_TOKEN"), "{e}"); + let ok = "a".repeat(32); + assert!(with_op(&[("PRINTAPI_OPERATOR_TOKEN", &ok)]).is_ok()); + let sess = format!("sess_{}", "a".repeat(40)); + assert!(with_op(&[("PRINTAPI_OPERATOR_TOKEN", &sess)]).is_err()); + let e = with_op(&[("PRINTAPI_TOKEN", OP)]).unwrap_err(); + assert!(e.contains("PRINTAPI_TOKEN"), "{e}"); + // surrounding whitespace never counts towards the length + let padded = format!(" {} ", "a".repeat(31)); + assert!(with_op(&[("PRINTAPI_OPERATOR_TOKEN", &padded)]).is_err()); + } + + #[test] + fn an_invalid_from_entry_stops_the_server() { + let e = with_op(&[("PRINTAPI_OPERATOR_FROM", "10.9.0.2,not-an-ip")]).unwrap_err(); + assert!(e.contains("PRINTAPI_OPERATOR_FROM"), "{e}"); + } + + #[test] + fn hosted_mode_comes_with_the_token() { + let c = with_op(&[]).unwrap(); + assert_eq!(c.destinations, Destinations::PublicOnly); + assert_eq!(c.fetches_per_org, Some(4)); + assert_eq!(c.fetch_cap(), 4); + // whatever signup says + let c = with_op(&[("PRINTAPI_SIGNUP", "closed")]).unwrap(); + assert_eq!(c.destinations, Destinations::PublicOnly); + assert_eq!(c.fetch_cap(), 4); + } + + #[test] + fn explicit_settings_beat_the_hosted_defaults() { + let c = with_op(&[ + ("PRINTAPI_PRIVATE_URLS", "allow"), + ("PRINTAPI_FETCHES_PER_ORG", "0"), + ]) + .unwrap(); + assert_eq!(c.destinations, Destinations::Any); + assert_eq!(c.fetch_cap(), 0); + let c = with_op(&[("PRINTAPI_FETCHES_PER_ORG", "9")]).unwrap(); + assert_eq!(c.fetch_cap(), 9); + } +} diff --git a/crates/server/src/server.rs b/crates/server/src/server.rs index 2506400..4d7eef8 100644 --- a/crates/server/src/server.rs +++ b/crates/server/src/server.rs @@ -57,6 +57,11 @@ pub struct Config { /// PRINTAPI_FETCHES_PER_ORG: payload downloads one org may have in flight; 0 = no cap. None: /// `MAX_FETCHES_PER_ORG` with open signup, else no cap (see `Config::fetch_cap`). pub fetches_per_org: Option, + /// PRINTAPI_OPERATOR_TOKEN: the credential of the `/operator/` API. Never a `Principal`: only + /// `operator_gate` reads it. None: every `/operator/` path is a 404. + pub operator_token: Option, + /// PRINTAPI_OPERATOR_FROM: the socket peers the operator token is accepted from. + pub operator_from: crate::proxy::TrustedProxies, } /// The terms a signup must accept (`PRINTAPI_TERMS_*`). The URLs are `http(s)` (checked at startup). @@ -93,6 +98,8 @@ impl Config { job_retention_days: None, terms: None, fetches_per_org: None, + operator_token: None, + operator_from: crate::proxy::TrustedProxies::default(), } } } @@ -193,6 +200,12 @@ pub struct AppState { /// A retention WAL truncate was blocked by a reader; the next pass retries it even if it /// changes no rows. wal_truncate_pending: std::sync::atomic::AtomicBool, + /// When the process started (the overview's uptime). + started: std::time::Instant, + /// The last retention pass that ran: when, and what it did (the operator overview). + last_purge: Mutex>, + /// The operator overview, kept for `operator::OVERVIEW_TTL`. + overview_cache: Mutex>, } /// Concurrent image renders (see `AppState::render_slots`). ponytail: one global cap, not per @@ -365,6 +378,9 @@ impl AppState { org_fetches: Mutex::new(std::collections::HashMap::new()), keys_in_flight: Mutex::new(std::collections::HashSet::new()), wal_truncate_pending: std::sync::atomic::AtomicBool::new(false), + started: std::time::Instant::now(), + last_purge: Mutex::new(None), + overview_cache: Mutex::new(None), } } } @@ -392,6 +408,8 @@ pub struct Req { /// The client's IP: the socket peer, or the address `X-Forwarded-For` names when the peer is a /// trusted proxy (`proxy::client_ip`). The signup throttle key and the access log use it. pub peer_ip: String, + /// The raw socket peer, never `X-Forwarded-For`. Only the operator gate reads it. + pub socket_peer: String, } impl Req { @@ -473,6 +491,9 @@ macro_rules! gate { }; } +mod operator; +pub use operator::is_operator_token; + fn jerr(status: u16, msg: impl AsRef) -> Resp { Resp::json(status, &json!({ "error": msg.as_ref() })) } @@ -779,6 +800,11 @@ impl From for SubmitErr { struct Ctx<'a> { s: &'a AppState, req: &'a Req, + /// The request carried the operator token (Authorization or a CloudPRNT path key) on a route + /// that is not `/operator/`. `handle` has already removed it, so every resolver sees no + /// credential; only `enrollment_org` still needs to know, because open enrollment would + /// otherwise take a request without a key. + operator_cred: bool, } /// The org `key` may enroll an agent into, or why it may not (see `Ctx::agent_register`): the @@ -791,7 +817,14 @@ fn enrollment_org( key: &str, root: bool, open: bool, + operator: bool, ) -> Result, StoreError> { + // The operator token enrolls nothing, not even with open enrollment. + if operator { + return Ok(Err( + "unknown agent key: issue one with POST /apikeys (the dashboard's Keys page)", + )); + } if root { return Ok(Ok(store::DEFAULT_ORG)); } @@ -811,7 +844,31 @@ fn enrollment_org( /// Route one request (every method and path except the `GET /agent/jobs` long-poll). pub fn handle(state: &AppState, req: &Req) -> Resp { - let cx = Ctx { s: state, req }; + let path = req.path(); + if path == "/operator" || path.starts_with("/operator/") { + return Ctx { + s: state, + req, + operator_cred: false, + } + .operator(); + } + // The operator token is no credential anywhere else: take it out of the request before any + // session, key, Basic, CloudPRNT or agent lookup can see it. + if let Some(token) = state.cfg.operator_token.as_deref() + && let Some(clean) = operator::without_operator_credential(req, token) + { + return route(state, &clean, true); + } + route(state, req, false) +} + +fn route(state: &AppState, req: &Req, operator_cred: bool) -> Resp { + let cx = Ctx { + s: state, + req, + operator_cred, + }; let r = match req.method.as_str() { "GET" => cx.get(), "HEAD" => Ok(cx.head()), @@ -2267,7 +2324,7 @@ impl Ctx<'_> { let (root, open) = (self.admin_ok(), self.cfg().open_enrollment); // Checked here so a refused key answers 401 before any body validation, and again below // in the same lock hold as the registration, so a revocation in between cannot slip by. - if let Err(m) = self.db(|c| enrollment_org(c, key, root, open))? { + if let Err(m) = self.db(|c| enrollment_org(c, key, root, open, self.operator_cred))? { return Ok(jerr(401, m)); } let mut printers = Vec::new(); @@ -2308,10 +2365,12 @@ impl Ctx<'_> { let name = name.as_str(); // First contact binds name->key; re-register requires the same key. let registered = self.db(|c| -> Result<_, StoreError> { - Ok(match enrollment_org(c, key, root, open)? { - Err(m) => Err(m), - Ok(org) => Ok(store::register_agent(c, name, key, &printers, org)), - }) + Ok( + match enrollment_org(c, key, root, open, self.operator_cred)? { + Err(m) => Err(m), + Ok(org) => Ok(store::register_agent(c, name, key, &printers, org)), + }, + ) })?; match registered { Err(m) => Ok(jerr(401, m)), @@ -2654,6 +2713,7 @@ pub fn retention_pass(state: &AppState, now: f64) -> Option { }) { Ok(p) => { state.wal_truncate_pending.store(p.wal_busy, Relaxed); + *state.last_purge.lock().unwrap_or_else(|e| e.into_inner()) = Some((now, p.clone())); Some(p) } Err(e) => { diff --git a/crates/server/src/server/operator.rs b/crates/server/src/server/operator.rs new file mode 100644 index 0000000..81780b8 --- /dev/null +++ b/crates/server/src/server/operator.rs @@ -0,0 +1,194 @@ +// printpapi — self-hosted PrintNode alternative. Elastic License 2.0 (see LICENSE). +//! The operator API under `/operator/`: one service-level credential (`PRINTAPI_OPERATOR_TOKEN`) +//! for the console of a hosted deployment. Inert without the token: every `/operator/` path is a +//! 404. The token is never a `Principal`: only `operator_gate` reads it, and on every other route +//! `without_operator_credential` takes it out of the request before any lookup runs. +use super::*; +use std::net::IpAddr; +use std::time::Duration; + +/// How long `GET /operator/overview` is served from memory. +/// ponytail: one cached value for every caller; a console polling every few seconds must not turn +/// into a count over `jobs` per poll. +const OVERVIEW_TTL: Duration = Duration::from_secs(10); + +/// Newest first, at most this many audit rows per page. +const AUDIT_MAX_LIMIT: i64 = 200; +const AUDIT_DEFAULT_LIMIT: i64 = 50; + +/// Is `key` the operator token (constant-time)? An empty key never is. +pub fn is_operator_token(cfg: &Config, key: &str) -> bool { + cfg.operator_token + .as_deref() + .is_some_and(|t| !key.is_empty() && auth::ct_eq(key, t)) +} + +/// The request with the operator token removed, or `None` when it carried none. The token can +/// arrive as a Bearer value, as the HTTP Basic username (the PrintNode layer's way) or as the +/// key in a CloudPRNT URL; it is no credential for any of them. +pub(super) fn without_operator_credential(req: &Req, token: &str) -> Option { + let header = req.header("authorization"); + let presented = match header.strip_prefix("Bearer ") { + Some(b) => b.to_string(), + None => printnode::basic_key(header), + }; + let in_header = !presented.is_empty() && auth::ct_eq(&presented, token); + let in_path = cloudprnt_route(req.path()) + .flatten() + .is_some_and(|k| auth::ct_eq(k, token)); + if !in_header && !in_path { + return None; + } + let mut clean = req.clone(); + if in_header { + clean.headers.remove("authorization"); + } + if in_path { + // an unknown key, answered like any other + clean.target = clean.target.replacen(token, "_", 1); + } + Some(clean) +} + +impl Ctx<'_> { + /// Everything under `/operator/`. Never cached, whatever the answer. + pub(super) fn operator(&self) -> Resp { + let mut r = self.operator_route(); + r.headers.push(("Cache-Control", "no-store".into())); + r + } + + /// The operator token, presented from a socket peer in `PRINTAPI_OPERATOR_FROM`. The peer is + /// the raw socket address: `X-Forwarded-For` (which `peer_ip` resolves) is never consulted, + /// or anyone who can reach a trusted proxy could name the console's address. Root does not + /// pass: its token is a different credential with a different reach. + fn operator_gate(&self) -> bool { + let cfg = self.cfg(); + let Some(token) = cfg.operator_token.as_deref() else { + return false; + }; + let Ok(peer) = self.req.socket_peer.parse::() else { + return false; + }; + // both sides are always evaluated: no early exit on a wrong token + let token_ok = auth::ct_eq(self.presented_key(), token); + let peer_ok = cfg.operator_from.contains(peer); + token_ok & peer_ok + } + + fn operator_route(&self) -> Resp { + if self.cfg().operator_token.is_none() { + return not_found(); + } + // a 401 before any 404: the gate does not tell which paths exist + if !self.operator_gate() { + return unauthorized(); + } + let r = match (self.req.method.as_str(), self.req.path()) { + ("GET", "/operator/overview") => self.operator_overview(), + ("GET", "/operator/audit") => self.operator_audit(), + _ => Ok(not_found()), + }; + r.unwrap_or_else(|e| { + eprintln!("internal error: {e}"); + jerr(500, "internal error") + }) + } + + fn operator_audit(&self) -> R { + let q = query_params(self.target()); + let int = |name: &str| -> Result, Resp> { + qfirst(&q, name) + .map(|v| { + v.parse::() + .map_err(|_| jerr(400, format!("bad {name}"))) + }) + .transpose() + }; + let org = gate!(int("org")); + let before_id = gate!(int("before_id")); + let limit = gate!(int("limit")).unwrap_or(AUDIT_DEFAULT_LIMIT); + if limit < 1 { + return Ok(jerr(400, "bad limit")); + } + let limit = limit.min(AUDIT_MAX_LIMIT); + let action = qfirst(&q, "action"); + // one row more than asked says whether there is a next page + let mut rows = self.db(|c| store::list_audit(c, org, action, before_id, limit + 1))?; + let more = rows.len() as i64 > limit; + rows.truncate(limit as usize); + let next = if more { + rows.last().map(|r| r.id) + } else { + None + }; + let entries: Vec = rows + .iter() + .map(|r| { + json!({ + "id": r.id, "at": r.at, "actor": r.actor, "action": r.action, + "org_id": r.org_id, "org_created_at": r.org_created_at, + "target": r.target, "reason": r.reason, + // written as JSON by the actions; anything else is shown as the text it is + "detail": r.detail.as_deref().map(|d| { + serde_json::from_str::(d).unwrap_or_else(|_| Value::String(d.into())) + }), + }) + }) + .collect(); + Ok(Resp::json( + 200, + &json!({ "entries": entries, "next_before_id": next }), + )) + } + + fn operator_overview(&self) -> R { + let mut cache = self + .s + .overview_cache + .lock() + .unwrap_or_else(|e| e.into_inner()); + if let Some((at, v)) = cache.as_ref() + && at.elapsed() < OVERVIEW_TTL + { + return Ok(Resp::json(200, v)); + } + let now = crate::now(); + let (n, (db_bytes, wal_bytes)) = self + .db(|c| Ok::<_, StoreError>((store::overview_counts(c, now)?, store::db_sizes(c)?)))?; + let purge = self + .s + .last_purge + .lock() + .unwrap_or_else(|e| e.into_inner()) + .clone(); + let today: serde_json::Map = store::JOB_STATES + .iter() + .zip(n.jobs_today) + .map(|(s, n)| (s.to_string(), json!(n))) + .collect(); + let v = json!({ + "orgs": n.orgs, + "orgs_active_7d": n.orgs_active_7d, + "signups_7d": n.signups_7d, + "jobs_this_month": n.jobs_this_month, + "failed_jobs_30d": n.failed_jobs_30d, + "jobs_today": today, + "server": { + "version": env!("CARGO_PKG_VERSION"), + "uptime_s": self.s.started.elapsed().as_secs_f64().floor(), + }, + "db": { "size_bytes": db_bytes, "wal_bytes": wal_bytes }, + "retention": { + "last_pass_at": purge.as_ref().map(|p| p.0), + "abandoned": purge.as_ref().map(|p| p.1.abandoned), + "scrubbed": purge.as_ref().map(|p| p.1.scrubbed), + "deleted": purge.as_ref().map(|p| p.1.deleted), + }, + // the console shows a section only when the server reports its feature + "features": [], + }); + *cache = Some((std::time::Instant::now(), v.clone())); + Ok(Resp::json(200, &v)) + } +} diff --git a/crates/server/src/store.rs b/crates/server/src/store.rs index f12821c..b4100b8 100644 --- a/crates/server/src/store.rs +++ b/crates/server/src/store.rs @@ -388,6 +388,14 @@ CREATE UNIQUE INDEX IF NOT EXISTS jobs_idem ON jobs(org_id, idempotency_key); CREATE TABLE IF NOT EXISTS api_keys( id INTEGER PRIMARY KEY AUTOINCREMENT, org_id INTEGER NOT NULL, label TEXT NOT NULL, key_hash TEXT NOT NULL UNIQUE, active INTEGER NOT NULL DEFAULT 1, created_at REAL NOT NULL); +-- The operator audit log: one row per `/operator/` write, kept for ever (never changed or deleted by +-- any API, not removed with an org). Ids, numbers and setting values only, no e-mail or name. +-- `org_created_at` keeps a reused org id apart from its predecessor. A table of its own, so the +-- Python-era tables keep their shape and the Python server ignores it. +CREATE TABLE IF NOT EXISTS operator_audit( + id INTEGER PRIMARY KEY AUTOINCREMENT, at REAL NOT NULL, actor TEXT NOT NULL, + action TEXT NOT NULL, org_id INTEGER, org_created_at REAL, target TEXT, reason TEXT, + detail TEXT); "; const MIGRATIONS: &[&str] = &[ @@ -423,6 +431,8 @@ CREATE INDEX IF NOT EXISTS jobs_hooks ON jobs(id) CREATE INDEX IF NOT EXISTS agents_org ON agents(org_id); -- the retention scan (`purge_jobs`) looks at terminal jobs by age CREATE INDEX IF NOT EXISTS jobs_state_finished ON jobs(state, finished_at); +-- the operator overview counts jobs of this month, today and the last week across all orgs +CREATE INDEX IF NOT EXISTS jobs_created ON jobs(created_at); "; /// The oldest queued job of one agent that has not passed its deadline (`?1` agent, `?2` now). @@ -1677,7 +1687,7 @@ pub fn expire_jobs(conn: &Connection, now: Option) -> Result { } /// What one `purge_jobs` pass did. -#[derive(Debug, Default, PartialEq, Eq)] +#[derive(Debug, Default, Clone, PartialEq, Eq)] pub struct Purged { /// Queued jobs older than the retention that never ran and had no deadline: failed /// (`error='retention'`) and cleared; the callback stays so the client hears the outcome. @@ -2195,6 +2205,164 @@ pub fn is_cloudprnt_agent(conn: &Connection, agent_id: i64) -> Result { == Some(1)) } +// --- operator audit log --------------------------------------------------------------------------- + +/// One audit row to write. `actor` is always `operator` (service-level identity). Content is ids, +/// numbers and setting values only: never an e-mail address, name or title. +#[derive(Debug, Default, Clone)] +pub struct AuditRow<'a> { + pub action: &'a str, + pub org_id: Option, + pub org_created_at: Option, + pub target: Option<&'a str>, + pub reason: Option<&'a str>, + pub detail: Option<&'a str>, +} + +/// One `operator_audit` row as read back. +#[derive(Debug, Clone, PartialEq)] +pub struct AuditEntry { + pub id: i64, + pub at: f64, + pub actor: String, + pub action: String, + pub org_id: Option, + pub org_created_at: Option, + pub target: Option, + pub reason: Option, + pub detail: Option, +} + +/// The `jobs` queries behind `GET /operator/overview`. Every one must be answered from an index +/// range (`jobs_created`, `jobs_state_finished`), never a scan: the console polls them. +/// ponytail: `INDEXED BY` because the planner prefers a covering scan of `jobs_org_created`, which +/// reads every row; the range on `created_at` alone is what the new index is for. +pub const OVERVIEW_JOB_QUERIES: [&str; 4] = [ + "SELECT COUNT(DISTINCT org_id) FROM jobs INDEXED BY jobs_created WHERE created_at >= ?1", + "SELECT COUNT(*) FROM jobs INDEXED BY jobs_created WHERE created_at >= ?1", + "SELECT COUNT(*) FROM jobs INDEXED BY jobs_state_finished WHERE state='failed' AND finished_at >= ?1", + "SELECT state, COUNT(*) FROM jobs INDEXED BY jobs_created WHERE created_at >= ?1 GROUP BY state", +]; + +/// Write one audit row inside the caller's transaction, so the action and its row commit or roll +/// back together. The actor is always `operator` (service-level identity). +/// ponytail: named operator accounts when more than one person holds the token. +pub fn insert_audit(tx: &Transaction, row: &AuditRow) -> Result { + tx.execute( + "INSERT INTO operator_audit(at, actor, action, org_id, org_created_at, target, reason, detail) \ + VALUES(?,?,?,?,?,?,?,?)", + params![ + crate::now(), + "operator", + row.action, + row.org_id, + row.org_created_at, + row.target, + row.reason, + row.detail + ], + )?; + Ok(tx.last_insert_rowid()) +} + +/// Audit rows newest first (by `id`), optionally one org's or one action's, older than `before_id`. +/// ponytail: no index beyond the key: the log is meant to stay under ~100 k rows, then prune by hand. +pub fn list_audit( + conn: &Connection, + org: Option, + action: Option<&str>, + before_id: Option, + limit: i64, +) -> Result> { + let mut st = conn.prepare_cached( + "SELECT id, at, actor, action, org_id, org_created_at, target, reason, detail \ + FROM operator_audit \ + WHERE (:org IS NULL OR org_id = :org) AND (:action IS NULL OR action = :action) \ + AND (:before IS NULL OR id < :before) \ + ORDER BY id DESC LIMIT :limit", + )?; + let rows = st.query_map( + named_params! {":org": org, ":action": action, ":before": before_id, ":limit": limit}, + |r| { + Ok(AuditEntry { + id: r.get(0)?, + at: r.get(1)?, + actor: r.get(2)?, + action: r.get(3)?, + org_id: r.get(4)?, + org_created_at: r.get(5)?, + target: r.get(6)?, + reason: r.get(7)?, + detail: r.get(8)?, + }) + }, + )?; + Ok(rows.collect::>()?) +} + +/// The numbers of `GET /operator/overview` that come from the tables. +#[derive(Debug, Default, Clone, PartialEq)] +pub struct OverviewCounts { + pub orgs: i64, + pub orgs_active_7d: i64, + pub signups_7d: i64, + pub jobs_this_month: i64, + pub failed_jobs_30d: i64, + /// Jobs created today (UTC) per state, in `JOB_STATES` order. + pub jobs_today: [i64; 5], +} + +pub const JOB_STATES: [&str; 5] = ["queued", "claimed", "done", "failed", "cancelled"]; + +pub fn overview_counts(conn: &Connection, now: f64) -> Result { + const DAY: f64 = 86_400.0; + let one = + |sql: &str, since: f64| -> Result { Ok(conn.query_row(sql, [since], |r| r.get(0))?) }; + let mut out = OverviewCounts { + // the seeded default org is no signup + orgs: conn.query_row("SELECT COUNT(*) FROM orgs", [], |r| r.get(0))?, + signups_7d: one( + "SELECT COUNT(*) FROM orgs WHERE id != 1 AND created_at >= ?1", + now - 7.0 * DAY, + )?, + orgs_active_7d: one(OVERVIEW_JOB_QUERIES[0], now - 7.0 * DAY)?, + jobs_this_month: one(OVERVIEW_JOB_QUERIES[1], month_start(now))?, + failed_jobs_30d: one(OVERVIEW_JOB_QUERIES[2], now - 30.0 * DAY)?, + jobs_today: [0; 5], + }; + let today = (now / DAY).floor() * DAY; + let mut st = conn.prepare_cached(OVERVIEW_JOB_QUERIES[3])?; + let rows = st.query_map([today], |r| { + Ok((r.get::<_, String>(0)?, r.get::<_, i64>(1)?)) + })?; + for row in rows { + let (state, n) = row?; + if let Some(i) = JOB_STATES.iter().position(|s| *s == state) { + out.jobs_today[i] = n; + } + } + Ok(out) +} + +/// Size of the database file and its `-wal` in bytes (0 for an in-memory DB or no WAL file). +pub fn db_sizes(conn: &Connection) -> Result<(i64, i64)> { + let pages: i64 = conn.query_row("PRAGMA page_count", [], |r| r.get(0))?; + let page_size: i64 = conn.query_row("PRAGMA page_size", [], |r| r.get(0))?; + let file: String = conn + .query_row( + "SELECT file FROM pragma_database_list WHERE name='main'", + [], + |r| r.get(0), + ) + .unwrap_or_default(); + let wal = if file.is_empty() { + 0 + } else { + std::fs::metadata(format!("{file}-wal")).map_or(0, |m| m.len() as i64) + }; + Ok((pages * page_size, wal)) +} + #[cfg(test)] mod tests { use super::*; @@ -3468,6 +3636,22 @@ mod tests { assert_eq!(on, 1); } + #[test] + fn the_overview_queries_on_jobs_never_scan_the_table() { + let conn = db(); + for sql in OVERVIEW_JOB_QUERIES { + let mut st = conn.prepare(&format!("EXPLAIN QUERY PLAN {sql}")).unwrap(); + let plan: Vec = st + .query_map([0.0], |r| r.get::<_, String>(3)) + .unwrap() + .map(Result::unwrap) + .collect(); + for line in &plan { + assert!(!line.contains("SCAN jobs"), "{sql}: {plan:?}"); + } + } + } + #[test] fn every_connection_has_secure_delete_on() { assert_eq!(q::(&db(), "PRAGMA secure_delete", []), 1); diff --git a/crates/server/tests/common/mod.rs b/crates/server/tests/common/mod.rs index 89a5d01..b9ca607 100644 --- a/crates/server/tests/common/mod.rs +++ b/crates/server/tests/common/mod.rs @@ -146,6 +146,7 @@ impl App { body: Bytes::new(), body_error: false, peer_ip: "127.0.0.1".into(), + socket_peer: "127.0.0.1".into(), }, } } @@ -281,6 +282,12 @@ impl Call<'_> { self } + /// The raw socket peer (what the operator gate checks), apart from the resolved `peer_ip`. + pub fn socket(mut self, ip: &str) -> Self { + self.req.socket_peer = ip.into(); + self + } + pub fn send(self) -> Reply { let Resp { status, diff --git a/crates/server/tests/http_operator.rs b/crates/server/tests/http_operator.rs new file mode 100644 index 0000000..7357b65 --- /dev/null +++ b/crates/server/tests/http_operator.rs @@ -0,0 +1,552 @@ +// printpapi — self-hosted PrintNode alternative. Elastic License 2.0 (see LICENSE). +//! The operator API: the gate (token + socket peer), hosted-mode plumbing, the audit log and the +//! overview. Everything is inert without `PRINTAPI_OPERATOR_TOKEN`. +mod common; + +use common::*; +use printpapi_server::dispatch::HttpFetcher; +use printpapi_server::http::spawn_test_server; +use printpapi_server::mail::SmtpMailer; +use printpapi_server::proxy::TrustedProxies; +use printpapi_server::server::{AppState, Config}; +use printpapi_server::store::{self, AuditRow, Db}; +use serde_json::{Value, json}; +use std::io::{Read, Write}; +use std::sync::Arc; +use std::time::Duration; + +const OP: &str = "operator-token-0123456789abcdef-xyz"; +const CONSOLE: &str = "10.9.0.2"; + +fn hosted_cfg(c: &mut Config) { + c.operator_token = Some(OP.into()); + c.operator_from = TrustedProxies::parse(CONSOLE).unwrap(); +} + +fn hosted() -> App { + App::with(hosted_cfg) +} + +/// A call as the console makes it: the operator token from the console's address. +fn op<'a>(app: &'a App, method: &str, target: &str) -> Call<'a> { + app.call(method, target).bearer(OP).socket(CONSOLE) +} + +fn audit(db: &Db, action: &str, org: Option) -> i64 { + db.with(|c| { + let tx = store::begin_tx(c).unwrap(); + let id = store::insert_audit( + &tx, + &AuditRow { + action, + org_id: org, + org_created_at: org.map(|_| 1_700_000_000.0), + target: Some("t:1"), + reason: Some("because"), + detail: Some(r#"{"quota":5}"#), + }, + ) + .unwrap(); + tx.commit().unwrap(); + id + }) +} + +// --- the gate ----------------------------------------------------------------------------------- + +#[test] +fn without_a_token_every_operator_path_is_a_404() { + let app = App::new(); + for (m, p) in [ + ("GET", "/operator/overview"), + ("GET", "/operator/audit"), + ("GET", "/operator/nothing"), + ("POST", "/operator/orgs"), + ("DELETE", "/operator/orgs/1"), + ] { + for auth in [None, Some("t"), Some(OP)] { + let mut c = app.call(m, p); + if let Some(a) = auth { + c = c.bearer(a); + } + let r = c.send(); + assert_eq!(r.status, 404, "{m} {p} {auth:?}"); + assert_eq!(r.header("cache-control"), Some("no-store"), "{m} {p}"); + } + } +} + +#[test] +fn the_token_works_from_a_listed_peer_and_nowhere_else() { + let app = hosted(); + let r = op(&app, "GET", "/operator/overview").send(); + assert_eq!(r.status, 200, "{}", r.text()); + // another socket peer: the token is an unknown credential + let r = op(&app, "GET", "/operator/overview") + .socket("127.0.0.1") + .send(); + assert_eq!(r.status, 401); + // no credential, a wrong one + assert_eq!( + app.call("GET", "/operator/overview") + .socket(CONSOLE) + .send() + .status, + 401 + ); + let r = app + .call("GET", "/operator/overview") + .bearer("not-the-token-not-the-token-not-the-token") + .socket(CONSOLE) + .send(); + assert_eq!(r.status, 401); +} + +#[test] +fn root_is_refused_on_operator_paths() { + let app = hosted(); + for peer in [CONSOLE, "127.0.0.1"] { + let r = app + .call("GET", "/operator/overview") + .bearer("t") + .socket(peer) + .send(); + assert_eq!(r.status, 401, "{peer}"); + } +} + +#[test] +fn a_header_naming_the_console_does_not_make_the_peer_the_console() { + // the resolved client (X-Forwarded-For behind a trusted proxy) is the console's address, the + // socket peer is not + let app = hosted(); + let r = op(&app, "GET", "/operator/overview") + .peer(CONSOLE) + .socket("203.0.113.9") + .send(); + assert_eq!(r.status, 401); +} + +fn raw(addr: std::net::SocketAddr, extra: &str) -> String { + let mut s = std::net::TcpStream::connect(addr).unwrap(); + s.set_read_timeout(Some(Duration::from_secs(5))).unwrap(); + write!( + s, + "GET /operator/overview HTTP/1.1\r\nHost: t\r\n{extra}Connection: close\r\n\r\n" + ) + .unwrap(); + let mut out = Vec::new(); + let _ = s.read_to_end(&mut out); + String::from_utf8_lossy(&out).into_owned() +} + +fn wire_state(tweak: impl FnOnce(&mut Config)) -> Arc { + let mut cfg = Config::new("t"); + cfg.long_poll_timeout_s = 0.3; + cfg.poll_interval_s = 0.05; + tweak(&mut cfg); + Arc::new(AppState::new( + cfg, + Db::open(":memory:").unwrap(), + Arc::new(SmtpMailer), + Arc::new(HttpFetcher::new(Duration::from_secs(1))), + )) +} + +#[test] +fn over_the_wire_the_gate_reads_the_socket_peer_not_x_forwarded_for() { + let auth = format!("Authorization: Bearer {OP}\r\n"); + // a trusted proxy (the loopback peer) forwards a header naming the console: still refused + let addr = spawn_test_server(wire_state(|c| { + c.operator_token = Some(OP.into()); + c.operator_from = TrustedProxies::parse(CONSOLE).unwrap(); + c.trusted_proxies = TrustedProxies::parse("127.0.0.1").unwrap(); + })); + let r = raw(addr, &format!("{auth}X-Forwarded-For: {CONSOLE}\r\n")); + assert!(r.starts_with("HTTP/1.1 401"), "{r}"); + assert!(r.to_lowercase().contains("cache-control: no-store"), "{r}"); + // the real socket peer in the list: accepted, and never cached + let addr = spawn_test_server(wire_state(|c| { + c.operator_token = Some(OP.into()); + c.operator_from = TrustedProxies::parse("127.0.0.1").unwrap(); + })); + let r = raw(addr, &auth); + assert!(r.starts_with("HTTP/1.1 200"), "{r}"); + assert!(r.to_lowercase().contains("cache-control: no-store"), "{r}"); +} + +#[test] +fn every_operator_response_is_no_store() { + let app = hosted(); + for (m, p, peer, tok) in [ + ("GET", "/operator/overview", CONSOLE, Some(OP)), + ("GET", "/operator/audit", CONSOLE, Some(OP)), + ("GET", "/operator/nothing", CONSOLE, Some(OP)), + ("GET", "/operator/overview", "127.0.0.1", Some(OP)), + ("GET", "/operator/overview", CONSOLE, None), + ("POST", "/operator/audit", CONSOLE, Some(OP)), + ("HEAD", "/operator/audit", CONSOLE, Some(OP)), + ] { + let mut c = app.call(m, p).socket(peer); + if let Some(t) = tok { + c = c.bearer(t); + } + let r = c.send(); + assert_eq!( + r.header("cache-control"), + Some("no-store"), + "{m} {p} {peer}" + ); + } +} + +#[test] +fn an_unknown_operator_path_is_a_404_behind_the_gate() { + let app = hosted(); + assert_eq!(op(&app, "GET", "/operator/nothing").send().status, 404); + assert_eq!(op(&app, "GET", "/operator/").send().status, 404); + // and a 401 before it, so the gate does not tell which paths exist + let r = app.call("GET", "/operator/nothing").socket(CONSOLE).send(); + assert_eq!(r.status, 401); +} + +// --- the operator token is no credential anywhere else ------------------------------------------ + +/// Every route of the docs/api.md table, concrete. +fn routes() -> Vec<(&'static str, &'static str)> { + vec![ + ("GET", "/"), + ("GET", "/health"), + ("GET", "/metrics"), + ("POST", "/jobs"), + ("GET", "/labels"), + ("POST", "/labels"), + ("GET", "/labels/1"), + ("PUT", "/labels/1"), + ("DELETE", "/labels/1"), + ("POST", "/orders"), + ("POST", "/integrations/shopify/orders"), + ("GET", "/jobs"), + ("GET", "/jobs/1"), + ("DELETE", "/jobs/1"), + ("GET", "/printers"), + ("GET", "/computers"), + ("POST", "/login"), + ("POST", "/signup"), + ("POST", "/password/reset"), + ("POST", "/password/reset/confirm"), + ("POST", "/logout"), + ("GET", "/me"), + ("PUT", "/me/password"), + ("POST", "/users"), + ("GET", "/users"), + ("DELETE", "/users/1"), + ("POST", "/orgs/1/users"), + ("POST", "/orgs"), + ("GET", "/orgs"), + ("GET", "/orgs/1"), + ("PUT", "/orgs/1"), + ("DELETE", "/orgs/1"), + ("GET", "/plans"), + ("POST", "/billing/webhook"), + ("POST", "/apikeys"), + ("GET", "/apikeys"), + ("DELETE", "/apikeys/1"), + ("POST", "/agent/register"), + ("GET", "/agent/jobs"), + ("GET", "/agent/jobs/1/payload"), + ("POST", "/agent/jobs/1/result"), + ("POST", "/cloudprnt"), + ("GET", "/cloudprnt"), + ("DELETE", "/cloudprnt"), + ] +} + +/// A server where the operator token happens to also be a valid client key and agent key: if any +/// route resolved it as a credential, it would answer differently from an anonymous request. +fn hosted_with_lookalike_keys(open: bool) -> App { + let app = App::with(|c| { + hosted_cfg(c); + c.open_enrollment = open; + }); + add_key(&app.db, "k", OP, store::DEFAULT_ORG); + register(&app.db, "pc", OP, &[decl("Z", false)], store::DEFAULT_ORG); + app +} + +#[test] +fn the_operator_token_is_no_credential_on_any_other_route() { + let app = hosted_with_lookalike_keys(false); + for (m, p) in routes() { + let body = json!({"name": "x", "printers": [], "email": "a@b.test", "password": PW}); + let anon = app.call(m, p).json(&body).send().status; + for (how, c) in [ + ("bearer", app.call(m, p).bearer(OP)), + ("basic", app.call(m, p).basic(OP)), + ( + "bearer from console", + app.call(m, p).bearer(OP).socket(CONSOLE), + ), + ] { + let r = c.json(&body).send(); + assert_eq!(r.status, anon, "{m} {p} as {how}: {}", r.text()); + } + } + // and the path key of a CloudPRNT URL + let anon = app.call("POST", "/cloudprnt/zzz").json(&json!({})).send(); + let r = app + .call("POST", &format!("/cloudprnt/{OP}")) + .json(&json!({"printerMAC": "00:11:22:33:44:55"})) + .send(); + assert_eq!(r.status, anon.status, "{}", r.text()); +} + +#[test] +fn enrollment_refuses_the_operator_token_even_with_open_enrollment() { + let app = App::with(|c| { + hosted_cfg(c); + c.open_enrollment = true; + }); + let body = json!({"name": "evil", "printers": [{"name": "P", "can_pdf": false}]}); + for c in [ + app.call("POST", "/agent/register").bearer(OP), + app.call("POST", "/agent/register").basic(OP), + ] { + let r = c.json(&body).send(); + assert_eq!(r.status, 401, "{}", r.text()); + } + assert_eq!(app.get("/computers", Some("t")).1, json!({"computers": []})); + // any other value still enrolls with open enrollment: that rule is unchanged + let r = app + .call("POST", "/agent/register") + .bearer("whatever") + .json(&body) + .send(); + assert_eq!(r.status, 200, "{}", r.text()); +} + +#[test] +fn the_long_poll_refuses_the_operator_token_too() { + let state = wire_state(hosted_cfg); + state.db.with(|c| { + store::register_agent(c, "pc", OP, &[decl("Z", false)], 1).unwrap(); + }); + let addr = spawn_test_server(state); + let mut s = std::net::TcpStream::connect(addr).unwrap(); + s.set_read_timeout(Some(Duration::from_secs(5))).unwrap(); + write!( + s, + "GET /agent/jobs HTTP/1.1\r\nHost: t\r\nAuthorization: Bearer {OP}\r\nConnection: close\r\n\r\n" + ) + .unwrap(); + let mut out = Vec::new(); + let _ = s.read_to_end(&mut out); + let out = String::from_utf8_lossy(&out); + assert!(out.starts_with("HTTP/1.1 401"), "{out}"); +} + +// --- audit ---------------------------------------------------------------------------------------- + +#[test] +fn the_audit_log_lists_newest_first_with_every_column() { + let app = hosted(); + let a = audit(&app.db, "org.update", Some(2)); + let b = audit(&app.db, "org.lock", Some(3)); + let (st, v) = { + let r = op(&app, "GET", "/operator/audit").send(); + (r.status, r.json()) + }; + assert_eq!(st, 200, "{v}"); + let rows = v["entries"].as_array().unwrap(); + assert_eq!(rows.len(), 2); + assert_eq!(rows[0]["id"], b); + assert_eq!(rows[1]["id"], a); + let r = &rows[0]; + assert_eq!(r["actor"], "operator"); + assert_eq!(r["action"], "org.lock"); + assert_eq!(r["org_id"], 3); + assert_eq!(r["org_created_at"], 1_700_000_000.0); + assert_eq!(r["target"], "t:1"); + assert_eq!(r["reason"], "because"); + assert_eq!(r["detail"], json!({"quota": 5})); + assert!(r["at"].as_f64().unwrap() > 1.0e9); + assert!(v["next_before_id"].is_null()); +} + +#[test] +fn audit_pages_by_before_id() { + let app = hosted(); + let ids: Vec = (0..5) + .map(|_| audit(&app.db, "org.update", Some(2))) + .collect(); + let (_, v) = app.get_op("/operator/audit?limit=2"); + let got: Vec = v["entries"] + .as_array() + .unwrap() + .iter() + .map(|e| e["id"].as_i64().unwrap()) + .collect(); + assert_eq!(got, vec![ids[4], ids[3]]); + assert_eq!(v["next_before_id"], ids[3]); + let (_, v) = app.get_op(&format!("/operator/audit?limit=2&before_id={}", ids[3])); + let got: Vec = v["entries"] + .as_array() + .unwrap() + .iter() + .map(|e| e["id"].as_i64().unwrap()) + .collect(); + assert_eq!(got, vec![ids[2], ids[1]]); + let (_, v) = app.get_op(&format!("/operator/audit?limit=2&before_id={}", ids[1])); + assert_eq!(v["entries"].as_array().unwrap().len(), 1); + assert!(v["next_before_id"].is_null()); +} + +#[test] +fn audit_filters_by_org_and_action_and_caps_the_limit() { + let app = hosted(); + audit(&app.db, "org.update", Some(2)); + audit(&app.db, "org.lock", Some(2)); + audit(&app.db, "org.update", Some(3)); + let (_, v) = app.get_op("/operator/audit?org=2"); + assert_eq!(v["entries"].as_array().unwrap().len(), 2); + let (_, v) = app.get_op("/operator/audit?action=org.update"); + assert_eq!(v["entries"].as_array().unwrap().len(), 2); + let (_, v) = app.get_op("/operator/audit?org=2&action=org.update"); + assert_eq!(v["entries"].as_array().unwrap().len(), 1); + for _ in 0..205 { + audit(&app.db, "org.update", Some(4)); + } + let (_, v) = app.get_op("/operator/audit?limit=1000"); + assert_eq!(v["entries"].as_array().unwrap().len(), 200); + assert!(v["next_before_id"].is_i64()); +} + +#[test] +fn audit_rejects_bad_parameters() { + let app = hosted(); + for q in ["limit=abc", "limit=0", "limit=-1", "before_id=x", "org=x"] { + let (st, _) = app.get_op(&format!("/operator/audit?{q}")); + assert_eq!(st, 400, "{q}"); + } +} + +#[test] +fn the_audit_log_is_read_only_here() { + let app = hosted(); + for m in ["POST", "PUT", "DELETE"] { + assert_eq!(op(&app, m, "/operator/audit").send().status, 404, "{m}"); + } +} + +// --- overview ------------------------------------------------------------------------------------- + +trait OpGet { + fn get_op(&self, target: &str) -> (u16, Value); +} + +impl OpGet for App { + fn get_op(&self, target: &str) -> (u16, Value) { + let r = op(self, "GET", target).send(); + (r.status, r.json()) + } +} + +#[test] +fn overview_counts_orgs_jobs_and_failures() { + let app = hosted(); + let (st, v) = app.get_op("/operator/overview"); + assert_eq!(st, 200); + // the seeded default org only; it is not a signup + assert_eq!(v["orgs"], 1); + assert_eq!(v["signups_7d"], 0); + assert_eq!(v["jobs_this_month"], 0); + assert_eq!(v["features"], json!([])); + assert_eq!( + v["jobs_today"], + json!({"queued": 0, "claimed": 0, "done": 0, "failed": 0, "cancelled": 0}) + ); +} + +#[test] +fn overview_reflects_data() { + let app = hosted(); + let org = create_org(&app.db, "Shop"); + let reg = register(&app.db, "pc", "ak", &[decl("Z", false)], org); + let pid = reg.pid("Z"); + let done = enqueue(&app.db, pid, b"secret-payload", |j| { + j.org_id = Some(org); + j.title = Some("secret-title".into()); + }); + let failed = enqueue(&app.db, pid, b"x", |j| j.org_id = Some(org)); + let _queued = enqueue(&app.db, pid, b"x", |j| j.org_id = Some(org)); + claim(&app.db, reg.computer_id); + finish(&app.db, done, reg.computer_id, true, None); + claim(&app.db, reg.computer_id); + finish(&app.db, failed, reg.computer_id, false, Some("boom")); + let (_, v) = app.get_op("/operator/overview"); + assert_eq!(v["orgs"], 2); + assert_eq!(v["signups_7d"], 1); + assert_eq!(v["orgs_active_7d"], 1); + assert_eq!(v["jobs_this_month"], 3); + assert_eq!(v["failed_jobs_30d"], 1); + assert_eq!( + v["jobs_today"], + json!({"queued": 1, "claimed": 0, "done": 1, "failed": 1, "cancelled": 0}) + ); + let text = v.to_string(); + assert!( + !text.contains("secret-title") && !text.contains("secret-payload"), + "{text}" + ); +} + +#[test] +fn overview_reports_the_server() { + let app = hosted(); + let (_, v) = app.get_op("/operator/overview"); + assert_eq!(v["server"]["version"], env!("CARGO_PKG_VERSION")); + assert!(v["server"]["uptime_s"].as_f64().unwrap() >= 0.0); + assert!(v["db"]["size_bytes"].as_i64().unwrap() > 0); + assert_eq!(v["db"]["wal_bytes"], 0); + assert!(v["retention"]["last_pass_at"].is_null()); +} + +#[test] +fn overview_reports_the_wal_of_a_file_database() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("p.db"); + let db = Db::open(path.to_str().unwrap()).unwrap(); + create_org(&db, "Shop"); + let app = App::on(db, hosted_cfg); + let (_, v) = app.get_op("/operator/overview"); + let wal = std::fs::metadata(dir.path().join("p.db-wal")).map_or(0, |m| m.len()); + assert!(wal > 0, "the write left a WAL"); + assert_eq!(v["db"]["wal_bytes"], wal); + assert!(v["db"]["size_bytes"].as_i64().unwrap() > 0); +} + +#[test] +fn overview_reports_the_last_retention_pass() { + let app = App::with(|c| { + hosted_cfg(c); + c.job_retention_days = Some(7); + }); + let now = printpapi_server::now(); + printpapi_server::server::retention_pass(&app.state, now).expect("a pass ran"); + let (_, v) = app.get_op("/operator/overview"); + let at = v["retention"]["last_pass_at"].as_f64().unwrap(); + assert!((at - now).abs() < 1.0); + for k in ["abandoned", "scrubbed", "deleted"] { + assert_eq!(v["retention"][k], 0, "{k}"); + } +} + +#[test] +fn overview_is_cached_for_ten_seconds() { + let app = hosted(); + let (_, first) = app.get_op("/operator/overview"); + create_org(&app.db, "Late"); + let (_, second) = app.get_op("/operator/overview"); + assert_eq!(first["orgs"], 1); + assert_eq!(second, first); +} diff --git a/crates/server/tests/store_compat.rs b/crates/server/tests/store_compat.rs index 0ada047..caa77f0 100644 --- a/crates/server/tests/store_compat.rs +++ b/crates/server/tests/store_compat.rs @@ -366,6 +366,18 @@ fn write_a_database_for_python_to_read() { .user_id; create_session(c, uid, "sess_rust", 3600.0, None).unwrap(); add_api_key(c, "rust-key", "pk_rust", DEFAULT_ORG).unwrap(); + // the new table is in the file Python opens, with a row in it + let tx = begin_tx(c).unwrap(); + insert_audit( + &tx, + &AuditRow { + action: "org.update", + org_id: Some(ORG), + ..AuditRow::default() + }, + ) + .unwrap(); + tx.commit().unwrap(); }); } @@ -403,3 +415,71 @@ fn a_python_database_gets_the_label_templates_table_at_startup() { assert_eq!(list.len(), 1); assert_eq!(list[0].spec.name, "shipping"); } + +#[test] +fn a_python_database_gets_the_operator_audit_table_and_the_python_tables_stay_as_they_were() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("python_v2.sqlite3"); + let fixture = concat!( + env!("CARGO_MANIFEST_DIR"), + "/tests/fixtures/python_v2.sqlite3" + ); + std::fs::copy(fixture, &path).unwrap(); + let columns = |path: &std::path::Path, table: &str| -> Vec { + let c = rusqlite::Connection::open(path).unwrap(); + let mut st = c.prepare(&format!("PRAGMA table_info({table})")).unwrap(); + st.query_map([], |r| r.get::<_, String>(1)) + .unwrap() + .map(Result::unwrap) + .collect() + }; + let python_tables = [ + "orgs", "users", "sessions", "agents", "printers", "jobs", "api_keys", + ]; + let before: Vec<_> = python_tables.iter().map(|t| columns(&path, t)).collect(); + assert!(columns(&path, "operator_audit").is_empty()); + + let db = Db::open(path.to_str().unwrap()).unwrap(); + assert_eq!( + columns(&path, "operator_audit"), + [ + "id", + "at", + "actor", + "action", + "org_id", + "org_created_at", + "target", + "reason", + "detail" + ] + ); + // the new table adds nothing to a table Python knows beyond the old migrations + for (t, was) in python_tables.iter().zip(&before) { + let now = columns(&path, t); + assert!( + was.iter().all(|c| now.contains(c)), + "{t}: {was:?} -> {now:?}" + ); + } + // a row survives a second start + db.with(|c| { + let tx = begin_tx(c).unwrap(); + insert_audit( + &tx, + &AuditRow { + action: "org.update", + org_id: Some(ORG), + ..AuditRow::default() + }, + ) + .unwrap(); + tx.commit().unwrap(); + }); + drop(db); + let db = Db::open(path.to_str().unwrap()).unwrap(); + let rows = db.with(|c| list_audit(c, None, None, None, 10)).unwrap(); + assert_eq!(rows.len(), 1); + assert_eq!(rows[0].action, "org.update"); + assert_eq!(rows[0].actor, "operator"); +} diff --git a/docs/operator.md b/docs/operator.md new file mode 100644 index 0000000..74e3401 --- /dev/null +++ b/docs/operator.md @@ -0,0 +1,111 @@ +# Operator API + +A hosted deployment has an operator: someone who looks after many customers' orgs and is not one +of them. The operator API is what a separate console talks to for that. It is generic (orgs, jobs +as numbers, an audit log) and nothing in it is specific to one business. **It is off unless +`PRINTAPI_OPERATOR_TOKEN` is set**: with the token unset, every path under `/operator/` answers +`404`, as if the API did not exist. + +This page covers the gate, hosted mode, the audit log and the read endpoints available so far. + +## The gate + +Two settings, both required together: + +| Variable | Meaning | +|---|---| +| `PRINTAPI_OPERATOR_TOKEN` | The credential of the operator API. At least 32 characters, not starting with `sess_`, different from `PRINTAPI_TOKEN`. Anything else stops the server at startup | +| `PRINTAPI_OPERATOR_FROM` | The addresses it is accepted from: IPs or CIDRs, same syntax as `PRINTAPI_TRUSTED_PROXIES` ([server](server.md#behind-a-reverse-proxy)). Required when the token is set | + +A request passes the gate when it carries the token as `Authorization: Bearer` **and** its socket +peer is in `PRINTAPI_OPERATOR_FROM`. The peer is the address the TCP connection came from. A +trusted proxy's `X-Forwarded-For` is never read for this, so a caller who can reach the proxy cannot +name the console's address. From any other peer the token is an unknown credential and the answer +is `401`. + +- The root token (`PRINTAPI_TOKEN`) is **not** accepted on `/operator/`: `401`. Otherwise the + address rule would bind only the operator token, and root could read the same data from anywhere. +- The operator token is **no credential anywhere else**. On every other route it is dropped before + a session, API key, HTTP Basic (PrintNode), CloudPRNT or agent key is looked up, so it answers as + if no credential had been sent; an agent cannot enroll with it, even with + `PRINTAPI_OPEN_ENROLLMENT=1`. +- Every `/operator/` response carries `Cache-Control: no-store`, the unauthorized and `404` ones too. +- With `LOG_REQUESTS`, the access log writes `/operator/` paths **without their query string** + (a search can name a customer). +- There is one operator identity. Every audit row says `actor = operator`. + +Keep the console off the public host. In a Caddy setup, answer `404` for `/operator/*` on the +public site and let the console reach printpapi over the internal network: + +```caddyfile +printpapi.example.com { + @operator path /operator/* + respond @operator 404 + reverse_proxy printpapi:3460 +} +``` + +## Hosted mode + +Setting the operator token turns on hosted mode, because strangers' jobs run on this server: + +- `PRINTAPI_PRIVATE_URLS` unset means `deny` (payload URLs, callbacks and event URLs may only + reach public addresses), whatever `PRINTAPI_SIGNUP` says. +- `PRINTAPI_FETCHES_PER_ORG` unset means `4`. + +Both are fixed at startup. Set either explicitly and your value wins, for example +`PRINTAPI_PRIVATE_URLS=allow`. Setting the token never changes what these mean on a later upgrade. + +## Audit log + +Table `operator_audit`: `id`, `at`, `actor`, `action`, `org_id`, `org_created_at`, `target`, +`reason`, `detail`. `org_created_at` tells an org apart from an older one that had the same id. + +- It holds **ids, numbers and setting values**, never an e-mail address, a name or a job title, + so deleting a customer does not leave one behind. +- It is kept for ever. No API changes or deletes a row, and deleting an org does not remove its + rows. It does not follow `PRINTAPI_JOB_RETENTION_DAYS`. Trim it by hand if it ever grows past + about 100 000 rows. +- It records `/operator/` actions only. Root's own routes (for example `GET /jobs`, which lists + titles across orgs) are **not** audited. +- It lives in a table of its own: the Python server of v2.x ignores it, and a rollback keeps it. + +### `GET /operator/audit` + +Newest first. Query: `org`, `action` (exact), `before_id`, `limit` (default 50, at most 200). + +```json +{ + "entries": [ + {"id": 12, "at": 1760000000.5, "actor": "operator", "action": "org.update", + "org_id": 3, "org_created_at": 1750000000.0, "target": null, + "reason": "quota raised after support request", "detail": {"job_quota": 500}} + ], + "next_before_id": 9 +} +``` + +`next_before_id` is the `id` to pass as `before_id` for the next page, `null` on the last one. +A parameter that is not an integer answers `400`. + +## Overview + +`GET /operator/overview` answers counts and server numbers. It never contains a job payload, title, +callback, idempotency key, key secret or password hash. + +```json +{ + "orgs": 41, "orgs_active_7d": 17, "signups_7d": 3, + "jobs_this_month": 5120, "failed_jobs_30d": 12, + "jobs_today": {"queued": 0, "claimed": 1, "done": 188, "failed": 2, "cancelled": 0}, + "server": {"version": "3.4.0", "uptime_s": 86400}, + "db": {"size_bytes": 12582912, "wal_bytes": 0}, + "retention": {"last_pass_at": 1760000000.0, "abandoned": 0, "scrubbed": 14, "deleted": 0}, + "features": [] +} +``` + +`orgs` counts every org including the default one; `signups_7d` does not count the default org. +`jobs_today` is the current UTC day. `retention` is `null` fields until the first pass has run. +`features` lists the optional sections this server offers, so a console can hide the ones an older +server lacks. The answer is cached for 10 seconds. diff --git a/docs/server.md b/docs/server.md index 90ed9f5..1478862 100644 --- a/docs/server.md +++ b/docs/server.md @@ -46,10 +46,12 @@ Environment variables: | `PRINTAPI_TERMS_VERSION` | *(unset: no consent asked)* | A non-empty version string, e.g. `2026-11-13`. Set: `POST /signup` must carry `accept_terms` equal to it, `GET /health` reports it with the links below, and the dashboard's sign-up form shows a checkbox for the terms and the data processing agreement. Each acceptance (org, user, version, time) is stored in the `terms_acceptances` table. See [Self-signup](api.md#self-signup). With `PRINTAPI_SIGNUP=open` and no version, startup prints a warning | | `PRINTAPI_TERMS_URL` | *(required with the version)* | `http(s)` link to the terms. Anything else, or a version without it, stops the server at startup | | `PRINTAPI_DPA_URL`, `PRINTAPI_PRIVACY_URL` | *(unset)* | Optional `http(s)` links to the data processing agreement and the privacy policy, shown next to the checkbox. Anything else stops the server at startup | -| `PRINTAPI_FETCHES_PER_ORG` | `4` with open signup, else `0` (no cap) | Payload downloads (`*_uri`, `*_uri_post`, `label_uri`) one org may have in flight at once; the next one answers `503`. A non-negative integer, `0` = no cap; anything else stops the server at startup. Keeps one hosted tenant from using every download slot; a single-org box has no reason for it, since four hung upstream hosts would then block every other fetching job | -| `PRINTAPI_PRIVATE_URLS` | `deny` with open signup, else `allow` | `deny`: payload URLs (`*_uri`, `*_uri_post`), job `callback_url`s and org `event_url`s may only reach public addresses — no loopback, LAN, link-local/cloud-metadata or other private ranges, checked after DNS on every redirect hop. `allow`: anywhere (a self-hosted box fetching PDFs from an internal service). Set `deny` whenever people you do not trust get keys | +| `PRINTAPI_FETCHES_PER_ORG` | `4` with open signup or an [operator token](operator.md#hosted-mode), else `0` (no cap) | Payload downloads (`*_uri`, `*_uri_post`, `label_uri`) one org may have in flight at once; the next one answers `503`. A non-negative integer, `0` = no cap; anything else stops the server at startup. Keeps one hosted tenant from using every download slot; a single-org box has no reason for it, since four hung upstream hosts would then block every other fetching job | +| `PRINTAPI_PRIVATE_URLS` | `deny` with open signup or an [operator token](operator.md#hosted-mode), else `allow` | `deny`: payload URLs (`*_uri`, `*_uri_post`), job `callback_url`s and org `event_url`s may only reach public addresses — no loopback, LAN, link-local/cloud-metadata or other private ranges, checked after DNS on every redirect hop. `allow`: anywhere (a self-hosted box fetching PDFs from an internal service). Set `deny` whenever people you do not trust get keys | | `PRINTAPI_TRUSTED_PROXIES` | *(unset: nobody)* | Comma-separated IPs or CIDRs (IPv4 and IPv6, e.g. `127.0.0.1,::1` or the one pinned proxy address `172.30.0.2` of the Compose example; list nothing wider) of the reverse proxies in front of printpapi. Only a request whose socket peer is listed has its `X-Forwarded-For` read: the rightmost entry that is not itself listed is the client, which the signup throttle (IPv6 per /64) and the `LOG_REQUESTS` line then use. Unset, the socket peer is the client, so behind a proxy every signup shares one throttle slot. An invalid entry stops the server at startup. See [Behind a reverse proxy](#behind-a-reverse-proxy) | | `PRINTAPI_OPEN_ENROLLMENT` | *(off)* | `1`: any Bearer value enrolls a new agent into the default org (the v2 rule). Off: a new agent needs an issued key or the root token | +| `PRINTAPI_OPERATOR_TOKEN` | *(unset: no operator API)* | Set: the [operator API](operator.md) under `/operator/` is on, for the console of a hosted deployment, and so is hosted mode (private URLs denied, 4 downloads per org, unless you set them). At least 32 characters, not starting with `sess_`, different from `PRINTAPI_TOKEN`; anything else stops the server at startup. Unset, every `/operator/` path answers `404` | +| `PRINTAPI_OPERATOR_FROM` | *(required with the operator token)* | Comma-separated IPs or CIDRs (the `PRINTAPI_TRUSTED_PROXIES` syntax) the operator token is accepted from, matched against the **socket peer**, never `X-Forwarded-For`. From any other address the token is an unknown credential. Missing or invalid with the token set stops the server at startup | ```bash PRINTAPI_TOKEN=change-me PRINT_DB=data/printpapi.db ./printpapi From 4f9e6fbba94d6cdd0fdb38dbefc71362740a80c7 Mon Sep 17 00:00:00 2001 From: Lukas Date: Sat, 14 Nov 2026 01:34:07 +0100 Subject: [PATCH 3/5] feat(server): operator read endpoints for orgs and their jobs GET /operator/orgs (derived status locked/new/idle/active, q over org name and user e-mail, status filter, keyset paging by org id), GET /operator/orgs/{id} (usage_by_day for the current UTC month, users, agents, printers, keys without secrets, terms history, lock) and GET /operator/orgs/{id}/jobs (metadata only, before_id paging). One correlated statement serves list and detail; new additive indexes (jobs(org_id), jobs(org_id, state), printers, users, terms) keep it off full scans, checked by an EXPLAIN QUERY PLAN test. New empty org_locks table (written by the lock endpoints later). Tests assert no payload, title, callback, idempotency key, key secret or hash, password hash or Shopify secret in any answer. docs/operator.md extended. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01TEvvb3zrZ3bLSGJbCBaEYX --- crates/server/src/server/operator.rs | 226 ++++++++++- crates/server/src/store.rs | 372 ++++++++++++++++++ crates/server/tests/http_operator.rs | 562 +++++++++++++++++++++++++++ crates/server/tests/store_compat.rs | 4 + docs/operator.md | 65 +++- 5 files changed, 1227 insertions(+), 2 deletions(-) diff --git a/crates/server/src/server/operator.rs b/crates/server/src/server/operator.rs index 81780b8..3b23dd5 100644 --- a/crates/server/src/server/operator.rs +++ b/crates/server/src/server/operator.rs @@ -16,6 +16,43 @@ const OVERVIEW_TTL: Duration = Duration::from_secs(10); const AUDIT_MAX_LIMIT: i64 = 200; const AUDIT_DEFAULT_LIMIT: i64 = 50; +/// The same paging bounds for the org and job lists. +const LIST_MAX_LIMIT: i64 = 200; +const LIST_DEFAULT_LIMIT: i64 = 50; + +/// `/operator/orgs/{id}` (false) or `/operator/orgs/{id}/jobs` (true), the id all digits. +fn org_route(path: &str) -> Option<(i64, bool)> { + let rest = path.strip_prefix("/operator/orgs/")?; + let (id, jobs) = match rest.split_once('/') { + Some((id, "jobs")) => (id, true), + Some(_) => return None, + None => (rest, false), + }; + if id.is_empty() || !id.bytes().all(|b| b.is_ascii_digit()) { + return None; + } + Some((id.parse().ok()?, jobs)) +} + +/// The date of day `n` of the month starting at `month_start`, `YYYY-MM-DD` (UTC). +fn day_label(month_start: f64, n: i64) -> String { + chrono::DateTime::from_timestamp(month_start as i64 + n * 86_400, 0) + .map_or_else(String::new, |d| d.format("%Y-%m-%d").to_string()) +} + +fn org_json(o: &store::OperatorOrg) -> Value { + json!({ + "id": o.id, "name": o.name, "created_at": o.created_at, "plan": o.plan, + "job_quota": o.job_quota, "jobs_this_month": o.jobs_this_month, + "queued_jobs": o.queued_jobs, "failed_today": o.failed_today, + "last_job_at": o.last_job_at, "agents_online": o.agents_online, + "agents_total": o.agents_total, "newest_agent_seen_at": o.newest_agent_seen_at, + "printers": o.printers, "locked": o.locked, "first_user_email": o.first_user_email, + "terms_version": o.terms_version, "terms_accepted_at": o.terms_accepted_at, + "status": o.status, + }) +} + /// Is `key` the operator token (constant-time)? An empty key never is. pub fn is_operator_token(cfg: &Config, key: &str) -> bool { cfg.operator_token @@ -84,9 +121,16 @@ impl Ctx<'_> { if !self.operator_gate() { return unauthorized(); } - let r = match (self.req.method.as_str(), self.req.path()) { + let path = self.req.path(); + let r = match (self.req.method.as_str(), path) { ("GET", "/operator/overview") => self.operator_overview(), ("GET", "/operator/audit") => self.operator_audit(), + ("GET", "/operator/orgs") => self.operator_orgs(), + ("GET", _) => match org_route(path) { + Some((id, false)) => self.operator_org(id), + Some((id, true)) => self.operator_org_jobs(id), + None => Ok(not_found()), + }, _ => Ok(not_found()), }; r.unwrap_or_else(|e| { @@ -95,6 +139,186 @@ impl Ctx<'_> { }) } + /// `limit` (1..=200, default 50) and an optional integer, from the query string. + fn paging(&self, cursor: &str) -> Result<(i64, Option), Resp> { + let q = query_params(self.target()); + let int = |name: &str| -> Result, Resp> { + qfirst(&q, name) + .map(|v| { + v.parse::() + .map_err(|_| jerr(400, format!("bad {name}"))) + }) + .transpose() + }; + let limit = int("limit")?.unwrap_or(LIST_DEFAULT_LIMIT); + if limit < 1 { + return Err(jerr(400, "bad limit")); + } + Ok((limit.min(LIST_MAX_LIMIT), int(cursor)?)) + } + + fn operator_orgs(&self) -> R { + let (limit, after) = gate!(self.paging("after")); + let q = query_params(self.target()); + let status = qfirst(&q, "status"); + if status.is_some_and(|s| !store::ORG_STATUSES.contains(&s)) { + return Ok(jerr(400, "bad status")); + } + let query = store::OrgQuery { + status, + q: qfirst(&q, "q"), + after: after.unwrap_or(0), + only: None, + // one more than asked says whether there is a next page + limit: limit + 1, + }; + let win = self.cfg().online_window_s; + let mut orgs = self.db(|c| store::operator_list_orgs(c, crate::now(), win, &query))?; + let more = orgs.len() as i64 > limit; + orgs.truncate(limit as usize); + let next = if more { + orgs.last().map(|o| o.id) + } else { + None + }; + let orgs: Vec = orgs.iter().map(org_json).collect(); + Ok(Resp::json( + 200, + &json!({ "orgs": orgs, "next_after": next }), + )) + } + + fn operator_org(&self, id: i64) -> R { + let now = crate::now(); + let win = self.cfg().online_window_s; + let month = store::month_start(now); + let found = self.db(|c| { + let Some(org) = store::operator_get_org(c, now, win, id)? else { + return Ok::<_, StoreError>(None); + }; + Ok(Some(( + org, + store::org_jobs_by_day(c, id, month)?, + store::operator_org_parts(c, id)?, + store::list_agents(c, win, Some(now), Some(id))?, + ))) + })?; + let Some((org, by_day, parts, agents)) = found else { + return Ok(not_found()); + }; + // every day of the month so far, quiet ones as zeros + let days = ((now - month) / 86_400.0).floor() as i64 + 1; + let usage: Vec = (0..days) + .map(|d| { + let (jobs, failed) = by_day + .iter() + .find(|(i, _, _)| *i == d) + .map_or((0, 0), |(_, j, f)| (*j, *f)); + json!({ "date": day_label(month, d), "jobs": jobs, "failed": failed }) + }) + .collect(); + let mut v = org_json(&org); + let o = v.as_object_mut().expect("an object"); + o.insert("usage_by_day".into(), json!(usage)); + o.insert( + "users".into(), + json!( + parts + .users + .iter() + .map(|u| json!({ + "id": u.id, "email": u.email, "created_at": u.created_at + })) + .collect::>() + ), + ); + o.insert( + "agents".into(), + json!(agents.iter().map(|a| json!({ + "id": a.id, "name": a.name, "last_seen_at": a.last_seen_at, "online": a.online + })).collect::>()), + ); + o.insert( + "printers".into(), + json!( + parts + .printers + .iter() + .map(|p| json!({ + "id": p.id, "name": p.name, "can_pdf": p.can_pdf, "state": p.state, + "agent_id": p.agent_id + })) + .collect::>() + ), + ); + o.insert( + "keys".into(), + json!( + parts + .keys + .iter() + .map(|k| json!({ + "id": k.id, "label": k.label, "active": k.active, "created_at": k.created_at + })) + .collect::>() + ), + ); + o.insert( + "terms".into(), + json!( + parts + .terms + .iter() + .map(|(version, at)| json!({ + "version": version, "accepted_at": at + })) + .collect::>() + ), + ); + o.insert( + "lock".into(), + json!(parts.lock.as_ref().map(|l| json!({ + "reason": l.reason, "locked_at": l.locked_at + }))), + ); + Ok(Resp::json(200, &v)) + } + + fn operator_org_jobs(&self, id: i64) -> R { + let (limit, before_id) = gate!(self.paging("before_id")); + let found = self.db(|c| { + if !store::org_exists(c, id)? { + return Ok::<_, StoreError>(None); + } + Ok(Some(store::operator_org_jobs(c, id, before_id, limit + 1)?)) + })?; + let Some(mut jobs) = found else { + return Ok(not_found()); + }; + let more = jobs.len() as i64 > limit; + jobs.truncate(limit as usize); + let next = if more { + jobs.last().map(|j| j.id) + } else { + None + }; + let jobs: Vec = jobs + .iter() + .map(|j| { + json!({ + "id": j.id, "created_at": j.created_at, "claimed_at": j.claimed_at, + "finished_at": j.finished_at, "type": j.type_, "mode": j.mode, + "state": j.state, "printer_id": j.printer_id, + "printer_name": j.printer_name, "copies": j.copies, "error": j.error, + }) + }) + .collect(); + Ok(Resp::json( + 200, + &json!({ "jobs": jobs, "next_before_id": next }), + )) + } + fn operator_audit(&self) -> R { let q = query_params(self.target()); let int = |name: &str| -> Result, Resp> { diff --git a/crates/server/src/store.rs b/crates/server/src/store.rs index b4100b8..258d642 100644 --- a/crates/server/src/store.rs +++ b/crates/server/src/store.rs @@ -396,6 +396,11 @@ CREATE TABLE IF NOT EXISTS operator_audit( id INTEGER PRIMARY KEY AUTOINCREMENT, at REAL NOT NULL, actor TEXT NOT NULL, action TEXT NOT NULL, org_id INTEGER, org_created_at REAL, target TEXT, reason TEXT, detail TEXT); +-- An org the operator has locked (a pure flag: quota and plan untouched). `org_created_at` keeps a +-- reused org id apart from its predecessor. A table of its own, like operator_audit. +CREATE TABLE IF NOT EXISTS org_locks( + org_id INTEGER PRIMARY KEY, org_created_at REAL NOT NULL, reason TEXT NOT NULL, + locked_at REAL NOT NULL); "; const MIGRATIONS: &[&str] = &[ @@ -433,6 +438,13 @@ CREATE INDEX IF NOT EXISTS agents_org ON agents(org_id); CREATE INDEX IF NOT EXISTS jobs_state_finished ON jobs(state, finished_at); -- the operator overview counts jobs of this month, today and the last week across all orgs CREATE INDEX IF NOT EXISTS jobs_created ON jobs(created_at); +-- the operator's org list and job list look at one org's jobs by id and by state; the three after +-- them are the per-org counts and e-mail lookups next to them +CREATE INDEX IF NOT EXISTS jobs_org ON jobs(org_id); +CREATE INDEX IF NOT EXISTS jobs_org_state ON jobs(org_id, state); +CREATE INDEX IF NOT EXISTS printers_org ON printers(org_id); +CREATE INDEX IF NOT EXISTS users_org ON users(org_id); +CREATE INDEX IF NOT EXISTS terms_org ON terms_acceptances(org_id, accepted_at); "; /// The oldest queued job of one agent that has not passed its deadline (`?1` agent, `?2` now). @@ -2300,6 +2312,366 @@ pub fn list_audit( Ok(rows.collect::>()?) } +// --- operator reads: orgs and their jobs -------------------------------------------------------- +// +// Metadata only. None of these statements selects a payload, title, callback URL, idempotency +// key, key hash, password hash or the Shopify secret, so none of them can leak one. + +/// One org as the console lists it. +#[derive(Debug, Clone, PartialEq)] +pub struct OperatorOrg { + pub id: i64, + pub name: String, + pub created_at: f64, + pub plan: Option, + pub job_quota: Option, + pub jobs_this_month: i64, + pub queued_jobs: i64, + pub failed_today: i64, + pub last_job_at: Option, + pub agents_online: i64, + pub agents_total: i64, + pub newest_agent_seen_at: Option, + pub printers: i64, + pub locked: bool, + pub first_user_email: Option, + pub terms_version: Option, + pub terms_accepted_at: Option, + /// `locked` | `new` | `idle` | `active` + pub status: String, +} + +/// The status values `GET /operator/orgs?status=` takes. +pub const ORG_STATUSES: [&str; 4] = ["locked", "new", "idle", "active"]; + +/// Orgs with their numbers, by id. Every subquery is correlated on `org_id`, so each one is an +/// index lookup per org (`jobs_org`, `jobs_org_state`, `jobs_org_created`, `agents_org`, +/// `printers_org`, `users_org`, `terms_org`): the cost is the page size, not the size of `jobs`. +/// `:status` filters on the derived status, which needs the numbers, so a filtered page computes +/// them for every org it passes over (ponytail: fine for thousands of orgs; past that, store the +/// status). `:q` is a LIKE pattern (backslash escapes) or NULL; `:only` an org id or NULL. +const OPERATOR_ORG_LIST_SQL: &str = r" +SELECT * FROM ( + SELECT *, + CASE WHEN locked THEN 'locked' + WHEN created_at >= :new_since THEN 'new' + WHEN last_job_at IS NULL OR last_job_at < :idle_since THEN 'idle' + ELSE 'active' END AS status + FROM ( + SELECT o.id, o.name, o.created_at, o.plan, o.job_quota, + (SELECT COUNT(*) FROM jobs j WHERE j.org_id = o.id AND j.created_at >= :month) AS jobs_this_month, + (SELECT COUNT(*) FROM jobs j WHERE j.org_id = o.id AND j.state = 'queued') AS queued_jobs, + (SELECT COUNT(*) FROM jobs j WHERE j.org_id = o.id AND j.created_at >= :today + AND j.state = 'failed') AS failed_today, + (SELECT MAX(j.created_at) FROM jobs j WHERE j.org_id = o.id) AS last_job_at, + (SELECT COUNT(*) FROM agents a WHERE a.org_id = o.id + AND a.last_seen_at >= :online_since) AS agents_online, + (SELECT COUNT(*) FROM agents a WHERE a.org_id = o.id) AS agents_total, + (SELECT MAX(a.last_seen_at) FROM agents a WHERE a.org_id = o.id) AS newest_agent_seen_at, + (SELECT COUNT(*) FROM printers p WHERE p.org_id = o.id) AS printers, + EXISTS(SELECT 1 FROM org_locks l WHERE l.org_id = o.id) AS locked, + (SELECT u.email FROM users u WHERE u.org_id = o.id AND u.email IS NOT NULL + ORDER BY u.id LIMIT 1) AS first_user_email, + (SELECT t.version FROM terms_acceptances t WHERE t.org_id = o.id + ORDER BY t.accepted_at DESC, t.id DESC LIMIT 1) AS terms_version, + (SELECT MAX(t.accepted_at) FROM terms_acceptances t WHERE t.org_id = o.id) AS terms_accepted_at + FROM orgs o + WHERE o.id > :after AND (:only IS NULL OR o.id = :only) + AND (:q IS NULL OR o.name LIKE :q ESCAPE '\' + OR EXISTS(SELECT 1 FROM users u WHERE u.org_id = o.id AND u.email LIKE :q ESCAPE '\')) + ) +) WHERE (:status IS NULL OR status = :status) +ORDER BY id LIMIT :limit"; + +/// What `operator_list_orgs` filters and pages by. `after` is the last org id of the previous page. +#[derive(Debug, Clone, Default)] +pub struct OrgQuery<'a> { + pub status: Option<&'a str>, + /// A plain search string: matched against org names and user e-mails, `%` and `_` literal. + pub q: Option<&'a str>, + pub after: i64, + pub only: Option, + pub limit: i64, +} + +fn like_pattern(q: &str) -> String { + let mut p = String::from("%"); + for c in q.chars() { + if matches!(c, '%' | '_' | '\\') { + p.push('\\'); + } + p.push(c); + } + p.push('%'); + p +} + +fn operator_org(r: &Row) -> rusqlite::Result { + Ok(OperatorOrg { + id: r.get("id")?, + name: r.get("name")?, + created_at: r.get("created_at")?, + plan: r.get("plan")?, + job_quota: r.get("job_quota")?, + jobs_this_month: r.get("jobs_this_month")?, + queued_jobs: r.get("queued_jobs")?, + failed_today: r.get("failed_today")?, + last_job_at: r.get("last_job_at")?, + agents_online: r.get("agents_online")?, + agents_total: r.get("agents_total")?, + newest_agent_seen_at: r.get("newest_agent_seen_at")?, + printers: r.get("printers")?, + locked: r.get("locked")?, + first_user_email: r.get("first_user_email")?, + terms_version: r.get("terms_version")?, + terms_accepted_at: r.get("terms_accepted_at")?, + status: r.get("status")?, + }) +} + +/// Orgs for `GET /operator/orgs`, by id, at most `query.limit`. +pub fn operator_list_orgs( + conn: &Connection, + now: f64, + online_window_s: f64, + query: &OrgQuery, +) -> Result> { + const DAY: f64 = 86_400.0; + let q = query.q.map(like_pattern); + let mut st = conn.prepare_cached(OPERATOR_ORG_LIST_SQL)?; + let rows = st.query_map( + named_params! { + ":new_since": now - 7.0 * DAY, + ":idle_since": now - 14.0 * DAY, + ":month": month_start(now), + ":today": (now / DAY).floor() * DAY, + ":online_since": now - online_window_s, + ":after": query.after, + ":only": query.only, + ":q": q, + ":status": query.status, + ":limit": query.limit, + }, + operator_org, + )?; + Ok(rows.collect::>()?) +} + +/// One org with the same numbers as the list. +pub fn operator_get_org( + conn: &Connection, + now: f64, + online_window_s: f64, + org_id: i64, +) -> Result> { + let q = OrgQuery { + only: Some(org_id), + after: i64::MIN, + limit: 1, + ..Default::default() + }; + Ok(operator_list_orgs(conn, now, online_window_s, &q)?.pop()) +} + +/// Jobs of one org per UTC day since `since` (the start of the month): (day index, jobs, failed). +pub fn org_jobs_by_day(conn: &Connection, org_id: i64, since: f64) -> Result> { + let mut st = conn.prepare_cached( + "SELECT CAST((created_at - :since) / 86400 AS INTEGER) AS day, COUNT(*), \ + SUM(state = 'failed') FROM jobs WHERE org_id = :org AND created_at >= :since \ + GROUP BY day ORDER BY day", + )?; + let rows = st.query_map(named_params! {":org": org_id, ":since": since}, |r| { + Ok((r.get(0)?, r.get(1)?, r.get(2)?)) + })?; + Ok(rows.collect::>()?) +} + +#[derive(Debug, Clone, PartialEq)] +pub struct OperatorUser { + pub id: i64, + pub email: String, + pub created_at: f64, +} + +#[derive(Debug, Clone, PartialEq)] +pub struct OperatorKey { + pub id: i64, + pub label: String, + pub active: bool, + pub created_at: f64, +} + +#[derive(Debug, Clone, PartialEq)] +pub struct OperatorPrinter { + pub id: i64, + pub name: String, + pub can_pdf: bool, + pub state: String, + pub agent_id: i64, +} + +#[derive(Debug, Clone, PartialEq)] +pub struct OperatorLock { + pub reason: String, + pub locked_at: f64, +} + +/// The lists of the org detail, apart from agents (`list_agents`). +pub struct OrgParts { + pub users: Vec, + pub printers: Vec, + pub keys: Vec, + /// (version, accepted_at), oldest first. + pub terms: Vec<(String, f64)>, + pub lock: Option, +} + +pub fn operator_org_parts(conn: &Connection, org_id: i64) -> Result { + let mut st = conn.prepare_cached( + "SELECT id, email, created_at FROM users WHERE org_id = ? AND email IS NOT NULL ORDER BY id", + )?; + let users = st + .query_map([org_id], |r| { + Ok(OperatorUser { + id: r.get(0)?, + email: r.get(1)?, + created_at: r.get(2)?, + }) + })? + .collect::>()?; + let mut st = conn.prepare_cached( + "SELECT id, name, can_pdf, state, agent_id FROM printers WHERE org_id = ? ORDER BY id", + )?; + let printers = st + .query_map([org_id], |r| { + Ok(OperatorPrinter { + id: r.get(0)?, + name: r.get(1)?, + can_pdf: r.get(2)?, + state: r.get(3)?, + agent_id: r.get(4)?, + }) + })? + .collect::>()?; + let mut st = conn.prepare_cached( + "SELECT id, label, active, created_at FROM api_keys WHERE org_id = ? ORDER BY id", + )?; + let keys = st + .query_map([org_id], |r| { + Ok(OperatorKey { + id: r.get(0)?, + label: r.get(1)?, + active: r.get(2)?, + created_at: r.get(3)?, + }) + })? + .collect::>()?; + let mut st = conn.prepare_cached( + "SELECT version, accepted_at FROM terms_acceptances WHERE org_id = ? \ + ORDER BY accepted_at, id", + )?; + let terms = st + .query_map([org_id], |r| Ok((r.get(0)?, r.get(1)?)))? + .collect::>()?; + let lock = conn + .query_row( + "SELECT reason, locked_at FROM org_locks WHERE org_id = ?", + [org_id], + |r| { + Ok(OperatorLock { + reason: r.get(0)?, + locked_at: r.get(1)?, + }) + }, + ) + .optional()?; + Ok(OrgParts { + users, + printers, + keys, + terms, + lock, + }) +} + +/// One job as the operator sees it: metadata, never the content. +#[derive(Debug, Clone, PartialEq)] +pub struct OperatorJob { + pub id: i64, + pub created_at: f64, + pub claimed_at: Option, + pub finished_at: Option, + pub type_: String, + pub mode: String, + pub state: String, + pub printer_id: i64, + pub printer_name: Option, + pub copies: i64, + pub error: Option, +} + +/// Newest first by id (`jobs_org` is ordered by id within an org, so there is no sort). +const OPERATOR_ORG_JOBS_SQL: &str = " +SELECT j.id, j.created_at, j.claimed_at, j.finished_at, j.type, j.mode, j.state, j.printer_id, + p.name, j.copies, j.error +FROM jobs j LEFT JOIN printers p ON p.id = j.printer_id +WHERE j.org_id = :org AND (:before IS NULL OR j.id < :before) +ORDER BY j.id DESC LIMIT :limit"; + +pub fn operator_org_jobs( + conn: &Connection, + org_id: i64, + before_id: Option, + limit: i64, +) -> Result> { + let mut st = conn.prepare_cached(OPERATOR_ORG_JOBS_SQL)?; + let rows = st.query_map( + named_params! {":org": org_id, ":before": before_id, ":limit": limit}, + |r| { + Ok(OperatorJob { + id: r.get(0)?, + created_at: r.get(1)?, + claimed_at: r.get(2)?, + finished_at: r.get(3)?, + type_: r.get(4)?, + mode: r.get(5)?, + state: r.get(6)?, + printer_id: r.get(7)?, + printer_name: r.get(8)?, + copies: r.get(9)?, + error: r.get(10)?, + }) + }, + )?; + Ok(rows.collect::>()?) +} + +fn explain(conn: &Connection, sql: &str, p: impl rusqlite::Params) -> Result> { + let mut st = conn.prepare(&format!("EXPLAIN QUERY PLAN {sql}"))?; + let rows = st.query_map(p, |r| r.get::<_, String>(3))?; + Ok(rows.collect::>()?) +} + +/// The query plan of the org list (for the test that keeps it on indexes). +pub fn explain_operator_org_list(conn: &Connection) -> Result> { + explain( + conn, + OPERATOR_ORG_LIST_SQL, + named_params! { + ":new_since": 0, ":idle_since": 0, ":month": 0, ":today": 0, ":online_since": 0, + ":after": 0, ":only": None::, ":q": "%a%", ":status": "active", ":limit": 50, + }, + ) +} + +pub fn explain_operator_org_jobs(conn: &Connection) -> Result> { + explain( + conn, + OPERATOR_ORG_JOBS_SQL, + named_params! {":org": 1, ":before": None::, ":limit": 50}, + ) +} + /// The numbers of `GET /operator/overview` that come from the tables. #[derive(Debug, Default, Clone, PartialEq)] pub struct OverviewCounts { diff --git a/crates/server/tests/http_operator.rs b/crates/server/tests/http_operator.rs index 7357b65..fd01e80 100644 --- a/crates/server/tests/http_operator.rs +++ b/crates/server/tests/http_operator.rs @@ -550,3 +550,565 @@ fn overview_is_cached_for_ten_seconds() { assert_eq!(first["orgs"], 1); assert_eq!(second, first); } + +// --- read: orgs and their jobs ---------------------------------------------------------------------- + +const DAY: f64 = 86_400.0; + +fn now() -> f64 { + printpapi_server::now() +} + +fn sql(db: &Db, q: &str, p: impl rusqlite::Params) { + db.with(|c| c.execute(q, p).unwrap()); +} + +/// A self-signup the way /signup makes one: org, first user, accepted terms. Returns the org id. +fn signup(db: &Db, name: &str, email: &str, terms: Option<&str>) -> i64 { + db.with(|c| store::signup(c, name, email, "PWHASHSENTINEL", None, terms)) + .unwrap() + .org_id +} + +fn age_org(db: &Db, org: i64, days: f64) { + sql( + db, + "UPDATE orgs SET created_at=? WHERE id=?", + rusqlite::params![now() - days * DAY, org], + ); +} + +/// A job of `org` on its printer (made on first use), created `ago` seconds ago. +fn job_at(app: &App, org: i64, ago: f64, tweak: impl FnOnce(&mut store::NewJob<'_>)) -> i64 { + let existing = app + .db + .with(|c| { + c.query_row( + "SELECT id FROM printers WHERE org_id=? LIMIT 1", + [org], + |r| r.get::<_, i64>(0), + ) + }) + .ok(); + let pid = match existing { + Some(p) => p, + None => register( + &app.db, + &format!("pc{org}"), + &format!("agent-key-{org}"), + &[decl("Z", false)], + org, + ) + .pid("Z"), + }; + let id = enqueue(&app.db, pid, b"PAYLOADSENTINEL", |j| { + j.org_id = Some(org); + tweak(j) + }); + sql( + &app.db, + "UPDATE jobs SET created_at=? WHERE id=?", + rusqlite::params![now() - ago, id], + ); + id +} + +fn org_row(v: &Value, id: i64) -> &Value { + v["orgs"] + .as_array() + .unwrap() + .iter() + .find(|o| o["id"] == id) + .unwrap_or_else(|| panic!("org {id} not in {v}")) +} + +fn names(v: &Value) -> Vec { + v["orgs"] + .as_array() + .unwrap() + .iter() + .map(|o| o["name"].as_str().unwrap().to_string()) + .collect() +} + +fn ids_of(v: &Value, key: &str) -> Vec { + v[key] + .as_array() + .unwrap() + .iter() + .map(|o| o["id"].as_i64().unwrap()) + .collect() +} + +#[test] +fn org_read_endpoints_need_the_gate_and_are_get_only() { + let app = hosted(); + for t in [ + "/operator/orgs", + "/operator/orgs/1", + "/operator/orgs/1/jobs", + ] { + assert_eq!(app.call("GET", t).socket(CONSOLE).send().status, 401, "{t}"); + assert_eq!( + app.call("GET", t).bearer("t").socket(CONSOLE).send().status, + 401, + "{t}" + ); + assert_eq!(op(&app, "DELETE", t).send().status, 404, "DELETE {t}"); + } + let r = op(&app, "GET", "/operator/orgs").send(); + assert_eq!(r.status, 200, "{}", r.text()); + assert_eq!(r.header("cache-control"), Some("no-store")); +} + +#[test] +fn org_list_has_every_field_with_its_numbers() { + let app = hosted(); + let acme = signup(&app.db, "Acme", "Boss@Acme.test", Some("2026-11")); + age_org(&app.db, acme, 30.0); + sql( + &app.db, + "UPDATE terms_acceptances SET accepted_at=? WHERE org_id=?", + rusqlite::params![1_700_000_000.0, acme], + ); + sql( + &app.db, + "UPDATE orgs SET plan='pro', job_quota=100 WHERE id=?", + [acme], + ); + let month = store::month_start(now()); + // one failed job today, one queued job from last month, one done job this month + let failed = job_at(&app, acme, 60.0, |_| {}); + let queued = job_at(&app, acme, 5.0 * DAY, |_| {}); + let done = job_at(&app, acme, 120.0, |_| {}); + sql( + &app.db, + "UPDATE jobs SET state='failed' WHERE id=?", + [failed], + ); + sql(&app.db, "UPDATE jobs SET state='done' WHERE id=?", [done]); + sql( + &app.db, + "UPDATE jobs SET created_at=? WHERE id=?", + rusqlite::params![month - 10.0, queued], + ); + // two agents: one seen just now, one long ago + let a2 = register(&app.db, "fresh", "k2", &[decl("L", true)], acme); + let seen = now() - 30.0; + sql( + &app.db, + "UPDATE agents SET last_seen_at=? WHERE id=?", + rusqlite::params![seen, a2.computer_id], + ); + sql( + &app.db, + "UPDATE agents SET last_seen_at=? WHERE org_id=? AND id!=?", + rusqlite::params![now() - 3.0 * DAY, acme, a2.computer_id], + ); + + let (st, v) = app.get_op("/operator/orgs"); + assert_eq!(st, 200, "{v}"); + let o = org_row(&v, acme); + assert_eq!(o["name"], "Acme"); + assert_eq!(o["plan"], "pro"); + assert_eq!(o["job_quota"], 100); + assert_eq!(o["jobs_this_month"], 2, "{o}"); + assert_eq!(o["queued_jobs"], 1, "{o}"); + assert_eq!(o["failed_today"], 1); + assert_eq!(o["agents_total"], 2); + assert_eq!(o["agents_online"], 1); + assert_eq!(o["printers"], 2); + assert!((o["newest_agent_seen_at"].as_f64().unwrap() - seen).abs() < 1.0); + assert!(o["last_job_at"].as_f64().unwrap() > now() - 200.0); + assert_eq!(o["locked"], false); + assert_eq!(o["first_user_email"], "boss@acme.test"); + assert_eq!(o["terms_version"], "2026-11"); + assert_eq!(o["terms_accepted_at"], 1_700_000_000.0); + assert!(o["created_at"].as_f64().unwrap() < now() - 29.0 * DAY); + assert_eq!(o["status"], "active"); + assert!(v["next_after"].is_null()); +} + +#[test] +fn org_status_is_locked_new_idle_or_active_and_filters() { + let app = hosted(); + let fresh = signup(&app.db, "Fresh", "f@x.test", None); + let idle = signup(&app.db, "Idle", "i@x.test", None); + let active = signup(&app.db, "Active", "a@x.test", None); + let quiet = signup(&app.db, "OldQuiet", "q@x.test", None); + let locked = signup(&app.db, "Locked", "l@x.test", None); + for o in [store::DEFAULT_ORG, idle, active, quiet, locked] { + age_org(&app.db, o, 40.0); + } + job_at(&app, idle, 20.0 * DAY, |_| {}); + job_at(&app, active, 2.0 * DAY, |_| {}); + // a locked org is locked even when it is new and busy + age_org(&app.db, locked, 1.0); + job_at(&app, locked, 60.0, |_| {}); + sql( + &app.db, + "INSERT INTO org_locks(org_id, org_created_at, reason, locked_at) VALUES(?,?,?,?)", + rusqlite::params![locked, now() - DAY, "unpaid invoice", now()], + ); + let (st, v) = app.get_op("/operator/orgs"); + assert_eq!(st, 200, "{v}"); + assert_eq!(org_row(&v, fresh)["status"], "new"); + assert_eq!(org_row(&v, idle)["status"], "idle"); + assert_eq!(org_row(&v, active)["status"], "active"); + assert_eq!(org_row(&v, quiet)["status"], "idle"); + assert_eq!(org_row(&v, locked)["status"], "locked"); + assert_eq!(org_row(&v, locked)["locked"], true); + for (s, want) in [ + ("locked", vec!["Locked"]), + ("new", vec!["Fresh"]), + ("active", vec!["Active"]), + ] { + let (st, v) = app.get_op(&format!("/operator/orgs?status={s}")); + assert_eq!(st, 200, "{v}"); + assert_eq!(names(&v), want, "{s}"); + } + let (_, v) = app.get_op("/operator/orgs?status=idle"); + let got = names(&v); + assert!(got.contains(&"Idle".to_string()) && got.contains(&"OldQuiet".to_string())); + assert!(!got.contains(&"Active".to_string())); + assert_eq!(app.get_op("/operator/orgs?status=bogus").0, 400); +} + +#[test] +fn org_search_matches_name_or_email_case_insensitively() { + let app = hosted(); + signup(&app.db, "Mueller Druck", "chef@mueller.test", None); + signup(&app.db, "Beta", "Anna@Gamma.test", None); + signup(&app.db, "Delta 100%", "d@x.test", None); + let q = |s: &str| { + let (st, v) = app.get_op(&format!("/operator/orgs?q={s}")); + assert_eq!(st, 200, "q={s}: {v}"); + names(&v) + }; + assert_eq!(q("mueller%20dr"), vec!["Mueller Druck"]); + assert_eq!(q("BETA"), vec!["Beta"]); + assert_eq!(q("anna@gamma"), vec!["Beta"]); + assert_eq!(q("CHEF@MUELLER"), vec!["Mueller Druck"]); + // % and _ are literal + assert_eq!(q("100%25"), vec!["Delta 100%"]); + assert_eq!(q("%25"), vec!["Delta 100%"]); + assert!(q("_").is_empty()); + assert!(q("nothing-like-this").is_empty()); +} + +#[test] +fn org_list_pages_by_id() { + let app = hosted(); + for i in 0..5 { + signup(&app.db, &format!("O{i}"), &format!("o{i}@x.test"), None); + } + // 6 orgs in all, the seeded default one included + let (st, v) = app.get_op("/operator/orgs?limit=4"); + assert_eq!(st, 200, "{v}"); + let first = ids_of(&v, "orgs"); + assert_eq!(first.len(), 4); + assert!(first.windows(2).all(|w| w[0] < w[1]), "ascending by id"); + let next = v["next_after"].as_i64().unwrap(); + assert_eq!(next, *first.last().unwrap()); + let (_, v) = app.get_op(&format!("/operator/orgs?limit=4&after={next}")); + let rest = ids_of(&v, "orgs"); + assert_eq!(rest.len(), 2); + assert!(rest[0] > next); + assert!(v["next_after"].is_null()); + // the filter pages too + let (_, v) = app.get_op("/operator/orgs?q=x.test&status=new&limit=2"); + assert_eq!(v["orgs"].as_array().unwrap().len(), 2); + assert!(v["next_after"].is_i64()); + for bad in ["limit=0", "limit=x", "after=x"] { + assert_eq!(app.get_op(&format!("/operator/orgs?{bad}")).0, 400, "{bad}"); + } + for i in 0..205 { + signup(&app.db, "Bulk", &format!("bulk{i}@b.test"), None); + } + let (_, v) = app.get_op("/operator/orgs?limit=1000"); + assert_eq!(v["orgs"].as_array().unwrap().len(), 200); + assert!(v["next_after"].is_i64()); +} + +#[test] +fn org_detail_has_usage_users_agents_printers_keys_terms_and_lock() { + let app = hosted(); + let acme = signup(&app.db, "Acme", "boss@acme.test", Some("v1")); + sql( + &app.db, + "INSERT INTO terms_acceptances(org_id, user_id, version, accepted_at) VALUES(?,1,'v2',?)", + rusqlite::params![acme, now() + 1.0], + ); + let month = store::month_start(now()); + let j1 = job_at(&app, acme, 1.0, |_| {}); + let j2 = job_at(&app, acme, 2.0, |_| {}); + let j0 = job_at(&app, acme, 3.0, |_| {}); + sql(&app.db, "UPDATE jobs SET state='failed' WHERE id=?", [j1]); + // last month does not count; the first day of this month does + sql( + &app.db, + "UPDATE jobs SET created_at=? WHERE id=?", + rusqlite::params![month - 5.0, j0], + ); + sql( + &app.db, + "UPDATE jobs SET created_at=? WHERE id=?", + rusqlite::params![month + 5.0, j2], + ); + add_key(&app.db, "shop", "KEYSECRET-1234567890", acme); + sql( + &app.db, + "UPDATE agents SET last_seen_at=? WHERE org_id=?", + rusqlite::params![now() - 3600.0, acme], + ); + let (st, v) = app.get_op(&format!("/operator/orgs/{acme}")); + assert_eq!(st, 200, "{v}"); + assert_eq!(v["name"], "Acme"); + assert_eq!(v["status"], "new"); + assert_eq!(v["jobs_this_month"], 2); + assert!(v["lock"].is_null()); + let usage = v["usage_by_day"].as_array().unwrap(); + assert_eq!(usage[0]["jobs"], 1, "{usage:?}"); + assert!(usage[0]["date"].as_str().unwrap().ends_with("-01")); + let total: i64 = usage.iter().map(|d| d["jobs"].as_i64().unwrap()).sum(); + let failed: i64 = usage.iter().map(|d| d["failed"].as_i64().unwrap()).sum(); + assert_eq!((total, failed), (2, 1)); + // every day of the month so far, none after today + assert_eq!(usage.len(), ((now() - month) / DAY).floor() as usize + 1); + let u = &v["users"][0]; + assert_eq!(u["email"], "boss@acme.test"); + assert!(u["id"].is_i64() && u["created_at"].is_f64()); + assert_eq!(v["users"].as_array().unwrap().len(), 1); + let a = &v["agents"][0]; + assert_eq!(a["name"], format!("pc{acme}")); + assert_eq!(a["online"], false); + assert!(a.get("last_seen_at").is_some()); + let p = &v["printers"][0]; + assert_eq!(p["name"], "Z"); + assert_eq!(p["can_pdf"], false); + assert_eq!(p["state"], "active"); + assert_eq!(p["agent_id"], a["id"]); + let k = &v["keys"][0]; + assert_eq!(k["label"], "shop"); + assert_eq!(k["active"], true); + assert!(k["created_at"].is_f64()); + let terms: Vec<&str> = v["terms"] + .as_array() + .unwrap() + .iter() + .map(|t| t["version"].as_str().unwrap()) + .collect(); + assert_eq!(terms, vec!["v1", "v2"]); + assert!(v["terms"][0]["accepted_at"].is_f64()); + assert_eq!(v["terms_version"], "v2"); + // a lock shows up with its reason + sql( + &app.db, + "INSERT INTO org_locks(org_id, org_created_at, reason, locked_at) VALUES(?,?,?,?)", + rusqlite::params![acme, 1.0, "unpaid invoice", 1_700_000_500.0], + ); + let (_, v) = app.get_op(&format!("/operator/orgs/{acme}")); + assert_eq!( + v["lock"], + json!({"reason": "unpaid invoice", "locked_at": 1_700_000_500.0}) + ); + assert_eq!(v["status"], "locked"); +} + +#[test] +fn org_detail_and_jobs_of_an_unknown_org_are_404() { + let app = hosted(); + // the seeded default org exists, so a 404 below is the org and not the route + assert_eq!(app.get_op("/operator/orgs/1").0, 200); + assert_eq!(app.get_op("/operator/orgs/1/jobs").0, 200); + for t in [ + "/operator/orgs/999", + "/operator/orgs/999/jobs", + "/operator/orgs/x", + "/operator/orgs/x/jobs", + ] { + assert_eq!(app.get_op(t).0, 404, "{t}"); + } +} + +#[test] +fn org_jobs_are_metadata_newest_first_and_paged() { + let app = hosted(); + let acme = signup(&app.db, "Acme", "boss@acme.test", None); + let other = signup(&app.db, "Other", "o@x.test", None); + let ids: Vec = (0..5) + .map(|i| { + job_at(&app, acme, 100.0 - i as f64, |j| { + j.title = Some("TITLESENTINEL".into()); + j.callback_url = Some("https://cb.example/CALLBACKSENTINEL".into()); + j.idempotency_key = Some(format!("IDEMSENTINEL{i}")); + j.copies = 2; + }) + }) + .collect(); + job_at(&app, other, 1.0, |_| {}); + sql( + &app.db, + "UPDATE jobs SET state='failed', error='printer on fire', finished_at=5.5, claimed_at=4.5 WHERE id=?", + [ids[4]], + ); + let (st, v) = app.get_op(&format!("/operator/orgs/{acme}/jobs?limit=2")); + assert_eq!(st, 200, "{v}"); + assert_eq!(ids_of(&v, "jobs"), vec![ids[4], ids[3]]); + assert_eq!(v["next_before_id"], ids[3]); + let j = &v["jobs"][0]; + assert_eq!(j["state"], "failed"); + assert_eq!(j["error"], "printer on fire"); + assert_eq!(j["finished_at"], 5.5); + assert_eq!(j["claimed_at"], 4.5); + assert_eq!(j["type"], "raw_base64"); + assert_eq!(j["mode"], "raw"); + assert_eq!(j["copies"], 2); + assert_eq!(j["printer_name"], "Z"); + assert!(j["printer_id"].is_i64() && j["created_at"].is_f64()); + // exactly these fields: no title, payload, callback or idempotency key + let mut keys: Vec<&String> = j.as_object().unwrap().keys().collect(); + keys.sort(); + assert_eq!( + keys, + vec![ + "claimed_at", + "copies", + "created_at", + "error", + "finished_at", + "id", + "mode", + "printer_id", + "printer_name", + "state", + "type" + ] + ); + let (_, v) = app.get_op(&format!( + "/operator/orgs/{acme}/jobs?limit=2&before_id={}", + ids[3] + )); + assert_eq!(ids_of(&v, "jobs"), vec![ids[2], ids[1]]); + let (_, v) = app.get_op(&format!("/operator/orgs/{acme}/jobs?before_id={}", ids[1])); + assert_eq!(v["jobs"].as_array().unwrap().len(), 1); + assert!(v["next_before_id"].is_null()); + // only this org's jobs, and bad parameters + let (_, v) = app.get_op(&format!("/operator/orgs/{acme}/jobs")); + assert_eq!(v["jobs"].as_array().unwrap().len(), 5); + for bad in ["limit=0", "limit=x", "before_id=x"] { + assert_eq!( + app.get_op(&format!("/operator/orgs/{acme}/jobs?{bad}")).0, + 400, + "{bad}" + ); + } +} + +#[test] +fn org_jobs_limit_is_capped_at_200() { + let app = hosted(); + let acme = signup(&app.db, "Acme", "boss@acme.test", None); + for _ in 0..205 { + job_at(&app, acme, 1.0, |_| {}); + } + let (st, v) = app.get_op(&format!("/operator/orgs/{acme}/jobs?limit=1000")); + assert_eq!(st, 200, "{v}"); + assert_eq!(v["jobs"].as_array().unwrap().len(), 200); + assert!(v["next_before_id"].is_i64()); +} + +#[test] +fn no_operator_read_answer_carries_a_secret_or_content() { + let app = hosted(); + let acme = signup(&app.db, "Acme", "boss@acme.test", Some("v1")); + sql( + &app.db, + "UPDATE orgs SET shopify_secret='SHOPIFYSENTINEL', event_url='https://ev.example/EVENTSENTINEL' WHERE id=?", + [acme], + ); + add_key(&app.db, "shop", "KEYSECRET-1234567890", acme); + register( + &app.db, + "pc", + "AGENTKEYSECRET-123", + &[decl("Z", false)], + acme, + ); + sql( + &app.db, + "UPDATE users SET password_hash='PWHASHSENTINEL' WHERE org_id=?", + [acme], + ); + job_at(&app, acme, 10.0, |j| { + j.title = Some("TITLESENTINEL".into()); + j.callback_url = Some("https://cb.example/CALLBACKSENTINEL".into()); + j.idempotency_key = Some("IDEMSENTINEL".into()); + }); + let mut forbidden: Vec = [ + "SHOPIFYSENTINEL", + "EVENTSENTINEL", + "KEYSECRET-1234567890", + "AGENTKEYSECRET-123", + "PWHASHSENTINEL", + "TITLESENTINEL", + "CALLBACKSENTINEL", + "IDEMSENTINEL", + "PAYLOADSENTINEL", + "password_hash", + "key_hash", + "api_key_hash", + "payload", + "callback_url", + "idempotency_key", + "shopify_secret", + "title", + ] + .iter() + .map(|s| s.to_string()) + .collect(); + forbidden.push(store::hash_key("KEYSECRET-1234567890")); + forbidden.push(store::hash_key("AGENTKEYSECRET-123")); + for t in [ + "/operator/orgs".to_string(), + "/operator/orgs?q=acme".to_string(), + format!("/operator/orgs/{acme}"), + format!("/operator/orgs/{acme}/jobs"), + ] { + let r = op(&app, "GET", &t).send(); + assert_eq!(r.status, 200, "{t}"); + let body = r.text(); + assert!(body.contains("Acme") || t.ends_with("/jobs"), "{t}: {body}"); + for f in &forbidden { + assert!(!body.contains(f.as_str()), "{t} leaks {f}: {body}"); + } + } +} + +#[test] +fn org_read_queries_use_indexes() { + let db = store::connect(":memory:").unwrap(); + store::init_db(&db).unwrap(); + for (name, plan) in [ + ("org list", store::explain_operator_org_list(&db).unwrap()), + ("org jobs", store::explain_operator_org_jobs(&db).unwrap()), + ] { + assert!(!plan.is_empty(), "{name}"); + for line in &plan { + for t in [ + "jobs", + "users", + "agents", + "printers", + "terms_acceptances", + "org_locks", + ] { + assert!( + !line.starts_with(&format!("SCAN {t}")), + "{name} scans {t}: {plan:#?}" + ); + } + assert!(!line.contains("TEMP B-TREE"), "{name} sorts: {plan:#?}"); + } + } +} diff --git a/crates/server/tests/store_compat.rs b/crates/server/tests/store_compat.rs index caa77f0..aa7e3eb 100644 --- a/crates/server/tests/store_compat.rs +++ b/crates/server/tests/store_compat.rs @@ -454,6 +454,10 @@ fn a_python_database_gets_the_operator_audit_table_and_the_python_tables_stay_as "detail" ] ); + assert_eq!( + columns(&path, "org_locks"), + ["org_id", "org_created_at", "reason", "locked_at"] + ); // the new table adds nothing to a table Python knows beyond the old migrations for (t, was) in python_tables.iter().zip(&before) { let now = columns(&path, t); diff --git a/docs/operator.md b/docs/operator.md index 74e3401..e448de9 100644 --- a/docs/operator.md +++ b/docs/operator.md @@ -6,7 +6,8 @@ as numbers, an audit log) and nothing in it is specific to one business. **It is `PRINTAPI_OPERATOR_TOKEN` is set**: with the token unset, every path under `/operator/` answers `404`, as if the API did not exist. -This page covers the gate, hosted mode, the audit log and the read endpoints available so far. +This page covers the gate, hosted mode, the audit log and the read endpoints available so far +(overview, orgs and their jobs). ## The gate @@ -109,3 +110,65 @@ callback, idempotency key, key secret or password hash. `jobs_today` is the current UTC day. `retention` is `null` fields until the first pass has run. `features` lists the optional sections this server offers, so a console can hide the ones an older server lacks. The answer is cached for 10 seconds. + +## Orgs and their jobs + +Metadata only. Never in any answer: a job's payload, title, callback URL or idempotency key, an +API or agent key (nor its hash), a password hash, or an org's Shopify secret. All three are `GET` +only, and an org that does not exist (or an id that is not a number) answers `404`. + +### `GET /operator/orgs` + +Query: `status` (`locked`, `new`, `idle` or `active`), `q`, `limit` (default 50, at most 200), +`after`. Ordered by org id, oldest first. + +- `q` matches a part of the org name or of a user's e-mail address. `%` and `_` mean themselves. + Case is ignored for ASCII letters only (SQLite `LIKE`). +- `status` is derived, in this order: `locked` (the org has a lock), `new` (created less than 7 + days ago), `idle` (no job in the last 14 days, or never one), otherwise `active`. +- `after` is the `next_after` of the previous page; `next_after` is `null` on the last page. + A parameter that is not an integer, or an unknown `status`, answers `400`. + +```json +{ + "orgs": [ + {"id": 3, "name": "Acme", "created_at": 1750000000.0, "plan": "pro", "job_quota": 500, + "jobs_this_month": 212, "queued_jobs": 0, "failed_today": 1, "last_job_at": 1760000000.0, + "agents_online": 1, "agents_total": 2, "newest_agent_seen_at": 1760000100.0, "printers": 3, + "locked": false, "first_user_email": "boss@acme.example", + "terms_version": "2026-11", "terms_accepted_at": 1750000000.0, "status": "active"} + ], + "next_after": null +} +``` + +`job_quota` is `null` for unlimited. `jobs_this_month` is the current UTC month, `failed_today` +counts jobs created today (UTC) that failed, `queued_jobs` all jobs still queued. An agent is +online when it polled in the last minute. The statement +runs on indexes only (one lookup per org), so a page costs its size, not the size of `jobs`. A +`status` filter computes the numbers of every org it passes over. + +### `GET /operator/orgs/{id}` + +The row above plus: + +| Field | Content | +|---|---| +| `usage_by_day` | every UTC day of the **current month** up to today: `{date, jobs, failed}`. Earlier months are not offered: with job retention they would be incomplete | +| `users` | `id`, `email`, `created_at` | +| `agents` | `id`, `name`, `last_seen_at`, `online` | +| `printers` | `id`, `name`, `can_pdf`, `state`, `agent_id` | +| `keys` | `id`, `label`, `active`, `created_at`: the key itself is never shown | +| `terms` | the acceptance history, oldest first: `version`, `accepted_at` | +| `lock` | `null`, or `{reason, locked_at}` while the org is locked | + +### `GET /operator/orgs/{id}/jobs` + +Query: `limit` (default 50, at most 200), `before_id`. Newest first by id. Each job has `id`, +`created_at`, `claimed_at`, `finished_at`, `type`, `mode`, `state`, `printer_id`, `printer_name`, +`copies` and `error`. `next_before_id` is the id to pass as `before_id` for the next page, `null` +on the last one. + +The reads add indexes (`jobs(org_id)`, `jobs(org_id, state)` and three small ones) to an existing +database at startup. They are additive and the Python server of v2.x ignores them. The `org_locks` +table that holds the lock row is created empty; locking itself comes with the write endpoints. From 78b58dbbaec2a6b166935d94f46b487ef00046c5 Mon Sep 17 00:00:00 2001 From: Lukas Date: Sat, 14 Nov 2026 01:47:02 +0100 Subject: [PATCH 4/5] feat(server): operator writes with audit rows: org update, lock, delete, create and invite, reset mail, key revoke PUT /operator/orgs/{id} (name, job_quota, plan, validated first, one transaction), lock and unlock via the org_locks table (a pure flag; lock cancels queued jobs; while locked POST /jobs, POST /orders, the Shopify webhook and PrintNode POST /printjobs answer 403 "org locked", checked next to check_quota in enqueue_job and in the fetch gate before any download), DELETE with name confirmation (never the default org; delete_org also removes org_locks rows), POST /operator/orgs with a random password hash and the reset mail as invitation after the commit, POST /operator/users/{id}/reset and DELETE /operator/keys/{id} with an org_id check. Each action is one store function and one transaction with its audit row; a failing audit insert rolls the change back (insert_audit no longer reports a refused insert as Conflict). Mail and the WAL truncate run after the commit; a failed mail writes user.reset_mail_failed. Audit content is ids and numbers only. docs/operator.md gains the write endpoints and the lock rollback caveat. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01TEvvb3zrZ3bLSGJbCBaEYX --- README.md | 2 +- crates/server/src/server.rs | 49 +- crates/server/src/server/operator.rs | 304 ++++- crates/server/src/store.rs | 307 ++++- crates/server/tests/http_operator.rs | 5 +- crates/server/tests/http_operator_writes.rs | 1291 +++++++++++++++++++ docs/api.md | 2 + docs/operator.md | 90 +- docs/server.md | 2 +- 9 files changed, 2018 insertions(+), 34 deletions(-) create mode 100644 crates/server/tests/http_operator_writes.rs diff --git a/README.md b/README.md index 5dd1013..7287afc 100644 --- a/README.md +++ b/README.md @@ -185,7 +185,7 @@ sponsored by PrintNode.* | [Recipes](docs/recipes.md) | print from n8n, Zapier, Make, curl in one HTTP node | | [E-commerce](docs/ecommerce.md) | WooCommerce plugin, Shopify webhook, `POST /orders` | | [Billing](docs/billing.md) | plans, checkout links, the signed provider webhook, org deletion | -| [Operator API](docs/operator.md) | for a hosted deployment: a service token, the audit log and the overview a separate console reads | +| [Operator API](docs/operator.md) | for a hosted deployment: a service token, the audit log, reads and writes (quota, lock, create, delete, reset mail, key revoke) a separate console uses | | [Migration](docs/migration.md) | upgrading from v2 (Python) to v3 (Rust): server, agents, changed defaults, rollback | | [Roadmap](docs/roadmap.md) | what shipped and what is next | diff --git a/crates/server/src/server.rs b/crates/server/src/server.rs index 4d7eef8..202677d 100644 --- a/crates/server/src/server.rs +++ b/crates/server/src/server.rs @@ -494,6 +494,9 @@ macro_rules! gate { mod operator; pub use operator::is_operator_token; +/// The answer of every submit path while the operator has locked the org. +const ORG_LOCKED: &str = "org locked"; + fn jerr(status: u16, msg: impl AsRef) -> Resp { Resp::json(status, &json!({ "error": msg.as_ref() })) } @@ -780,6 +783,8 @@ fn fetches_payload(type_v: &Value) -> bool { enum SubmitErr { Fetch(String), Quota(String), + /// The org is locked by the operator: 403, whichever way the job came in. + Locked, Invalid(String), /// Too many renders or downloads running; the client may retry. Busy(String), @@ -1115,6 +1120,26 @@ impl Ctx<'_> { )) } + /// The body of a reset mail: `lead`, the link and the token. The link is built from PUBLIC_URL + /// only. Deriving it from the Host header would let anyone who can send this server a request + /// mail a *valid* token pointing at their own host; without the env var the mail carries the + /// bare token instead. + fn reset_mail_text(&self, lead: &str, tok: &str) -> String { + let public_url = &self.cfg().public_url; + let link = if public_url.is_empty() { + String::new() + } else { + format!("\nOpen {public_url}/?reset={tok}\n") + }; + format!( + "{lead}\n\ + {link}\ntoken: {tok}\n\n\ + It is valid for {} minutes and works once. \ + If this was not you, ignore this message.\n", + (self.cfg().reset_ttl_s / 60.0).floor() as i64 + ) + } + /// Always 200, whether or not the address exists — the answer must not enumerate accounts. A /// mail goes out only for a real one. fn password_reset(&self) -> R { @@ -1132,21 +1157,9 @@ impl Ctx<'_> { let tok = auth::new_session_token(); let ttl = self.cfg().reset_ttl_s; self.db(|c| store::create_password_reset(c, user.id, &tok, ttl, None))?; - // The link is built from PUBLIC_URL only. Deriving it from the Host header would let - // anyone who can send this server a request mail a *valid* token pointing at their - // own host; without the env var the mail carries the bare token instead. - let public_url = &self.cfg().public_url; - let link = if public_url.is_empty() { - String::new() - } else { - format!("\nOpen {public_url}/?reset={tok}\n") - }; - let text = format!( - "Someone asked to reset the printpapi password for {email}.\n\ - {link}\ntoken: {tok}\n\n\ - It is valid for {} minutes and works once. \ - If this was not you, ignore this message.\n", - (ttl / 60.0).floor() as i64 + let text = self.reset_mail_text( + &format!("Someone asked to reset the printpapi password for {email}."), + &tok, ); // a broken mail server must not answer differently if let Err(e) = self @@ -1273,6 +1286,7 @@ impl Ctx<'_> { }; // One closure, so a retry cannot see "no job yet" and then a quota the original used up. let checked = self.db(|c| { + store::check_not_locked(c, printer.org_id)?; if let Some(key) = key && let Some(e) = store::find_job_by_key(c, printer.org_id, key)? { @@ -1284,6 +1298,7 @@ impl Ctx<'_> { Ok(Some(e)) => return Ok(Gate2::Existing(e)), Ok(None) => {} Err(StoreError::QuotaExceeded(m)) => return Err(SubmitErr::Quota(m)), + Err(StoreError::Locked) => return Err(SubmitErr::Locked), Err(e) => return Err(SubmitErr::Store(e)), } if !fetch { @@ -1396,6 +1411,7 @@ impl Ctx<'_> { Ok(e) } Err(StoreError::QuotaExceeded(m)) => Err(SubmitErr::Quota(m)), + Err(StoreError::Locked) => Err(SubmitErr::Locked), Err(StoreError::UnknownPrinter(m)) => Err(SubmitErr::Invalid(m)), Err(e) => Err(SubmitErr::Store(e)), } @@ -1437,6 +1453,7 @@ impl Ctx<'_> { Ok(e) => Ok(Resp::json(200, &json!({ "job_id": e.job_id }))), Err(SubmitErr::Fetch(m)) => Ok(jerr(502, format!("downstream: {m}"))), Err(SubmitErr::Quota(m)) => Ok(jerr(402, m)), + Err(SubmitErr::Locked) => Ok(jerr(403, ORG_LOCKED)), Err(SubmitErr::Invalid(m)) => Ok(jerr(400, m)), Err(SubmitErr::Busy(m)) => Ok(jerr(503, m)), Err(SubmitErr::InProgress(m)) => Ok(jerr(409, m)), @@ -1512,6 +1529,7 @@ impl Ctx<'_> { match self.enqueue(&job) { Ok(e) => Ok(Resp::json(200, &json!({ "job_id": e.job_id }))), Err(SubmitErr::Quota(m)) => Ok(jerr(402, m)), + Err(SubmitErr::Locked) => Ok(jerr(403, ORG_LOCKED)), Err( SubmitErr::Invalid(m) | SubmitErr::Fetch(m) @@ -1819,6 +1837,7 @@ impl Ctx<'_> { Ok(e) => Resp::json(201, &json!(e.job_id)), Err(SubmitErr::Fetch(m)) => self.pn_error(502, "DownstreamError", m), Err(SubmitErr::Quota(m)) => self.pn_error(402, "QuotaExceeded", m), + Err(SubmitErr::Locked) => self.pn_error(403, "Forbidden", ORG_LOCKED), Err(SubmitErr::Invalid(m)) => self.pn_error(400, "BadRequest", m), Err(SubmitErr::Busy(m)) => self.pn_error(503, "ServiceUnavailable", m), // ponytail: unreachable today, this layer takes no idempotency key diff --git a/crates/server/src/server/operator.rs b/crates/server/src/server/operator.rs index 3b23dd5..79ace5c 100644 --- a/crates/server/src/server/operator.rs +++ b/crates/server/src/server/operator.rs @@ -20,18 +20,71 @@ const AUDIT_DEFAULT_LIMIT: i64 = 50; const LIST_MAX_LIMIT: i64 = 200; const LIST_DEFAULT_LIMIT: i64 = 50; -/// `/operator/orgs/{id}` (false) or `/operator/orgs/{id}/jobs` (true), the id all digits. -fn org_route(path: &str) -> Option<(i64, bool)> { +/// The longest reason the audit log takes: it is kept for ever. +const REASON_MAX: usize = 500; +/// The shortest reason a lock needs. +const LOCK_REASON_MIN: usize = 8; +/// The longest org name, in characters. +const NAME_MAX: usize = 200; + +/// `/operator/orgs/{id}` with its suffix (`""`, `"jobs"`, `"lock"` or `"unlock"`), the id all +/// digits. +fn org_route(path: &str) -> Option<(i64, &str)> { let rest = path.strip_prefix("/operator/orgs/")?; - let (id, jobs) = match rest.split_once('/') { - Some((id, "jobs")) => (id, true), + let (id, suffix) = match rest.split_once('/') { + Some((id, s @ ("jobs" | "lock" | "unlock"))) => (id, s), Some(_) => return None, - None => (rest, false), + None => (rest, ""), }; if id.is_empty() || !id.bytes().all(|b| b.is_ascii_digit()) { return None; } - Some((id.parse().ok()?, jobs)) + Some((id.parse().ok()?, suffix)) +} + +/// The optional `reason` of a write body: absent, null or blank is none; anything but a string, +/// or a string over `REASON_MAX` characters, is a 400. `min` characters make it required. +fn reason_of(body: &Obj, min: usize) -> Gate> { + let reason = match body.get("reason") { + None | Some(Value::Null) => None, + Some(Value::String(s)) => Some(printnode::py_trim(s).to_string()).filter(|s| !s.is_empty()), + Some(_) => return Err(jerr(400, "reason must be a string")), + }; + if reason + .as_ref() + .is_some_and(|r| r.chars().count() > REASON_MAX) + { + return Err(jerr(400, "reason is too long")); + } + if min > 0 && reason.as_ref().is_none_or(|r| r.chars().count() < min) { + return Err(jerr( + 400, + format!("reason of at least {min} characters required"), + )); + } + Ok(reason) +} + +/// A required, trimmed, non-empty string field of at most `NAME_MAX` characters. +fn name_of(v: Option<&Value>, what: &str) -> Gate { + match v { + Some(Value::String(s)) + if !printnode::py_trim(s).is_empty() && s.chars().count() <= NAME_MAX => + { + Ok(printnode::py_trim(s).to_string()) + } + _ => Err(jerr( + 400, + format!("{what} must be a non-empty string of at most {NAME_MAX} characters"), + )), + } +} + +/// The `org_id` a write names to prove its page is not stale. +fn org_id_of(body: &Obj) -> Gate { + body.get("org_id") + .and_then(Value::as_i64) + .ok_or_else(|| jerr(400, "org_id required")) } /// The date of day `n` of the month starting at `month_start`, `YYYY-MM-DD` (UTC). @@ -126,12 +179,24 @@ impl Ctx<'_> { ("GET", "/operator/overview") => self.operator_overview(), ("GET", "/operator/audit") => self.operator_audit(), ("GET", "/operator/orgs") => self.operator_orgs(), - ("GET", _) => match org_route(path) { - Some((id, false)) => self.operator_org(id), - Some((id, true)) => self.operator_org_jobs(id), - None => Ok(not_found()), + ("POST", "/operator/orgs") => self.operator_org_create(), + (m, _) => match (m, org_route(path)) { + ("GET", Some((id, ""))) => self.operator_org(id), + ("GET", Some((id, "jobs"))) => self.operator_org_jobs(id), + ("PUT", Some((id, ""))) => self.operator_org_update(id), + ("DELETE", Some((id, ""))) => self.operator_org_delete(id), + ("POST", Some((id, "lock"))) => self.operator_org_lock(id), + ("POST", Some((id, "unlock"))) => self.operator_org_unlock(id), + ("POST", None) => match id_of(path, "/operator/users/", "/reset") { + Some(uid) => self.operator_user_reset(uid), + None => Ok(not_found()), + }, + ("DELETE", None) => match id_of(path, "/operator/keys/", "") { + Some(kid) => self.operator_key_revoke(kid), + None => Ok(not_found()), + }, + _ => Ok(not_found()), }, - _ => Ok(not_found()), }; r.unwrap_or_else(|e| { eprintln!("internal error: {e}"); @@ -157,6 +222,223 @@ impl Ctx<'_> { Ok((limit.min(LIST_MAX_LIMIT), int(cursor)?)) } + /// Reset mails and invitations need a mail server and a `PUBLIC_URL` to link to. + fn mail_ready(&self) -> bool { + self.cfg().reset_enabled && !self.cfg().public_url.is_empty() + } + + /// Send `text` to `to`. A mail that did not go out writes a second audit row (`row`, as + /// `user.reset_mail_failed`); it names ids only. + fn send_operator_mail( + &self, + to: &str, + subject: &str, + text: &str, + row: &store::AuditRow, + ) -> bool { + let sent = matches!(self.s.mailer.send(to, subject, text), Ok(true)); + if !sent { + eprintln!("operator mail failed"); + let note = store::AuditRow { + action: "user.reset_mail_failed", + ..row.clone() + }; + if let Err(e) = self.db(|c| store::operator_audit_note(c, ¬e)) { + eprintln!("audit row for a failed mail not written: {e}"); + } + } + sent + } + + fn operator_org_update(&self, id: i64) -> R { + let body = gate!(self.read_obj()); + let reason = gate!(reason_of(&body, 0)); + let mut update = store::OrgUpdate::default(); + let mut detail = serde_json::Map::new(); + let name; + if body.contains_key("name") { + name = gate!(name_of(body.get("name"), "name")); + update.name = Some(&name); + detail.insert("name".into(), json!(true)); + } + if let Some(plan_v) = body.get("plan") { + let Some(plan) = billing::find(&self.cfg().plans, plan_v) else { + return Ok(jerr(400, format!("unknown plan: {}", repr(plan_v)))); + }; + update.plan = Some((&plan.id, plan.jobs)); + detail.insert("plan".into(), json!(plan.id)); + detail.insert("job_quota".into(), json!(plan.jobs)); + } + if let Some(quota) = body.get("job_quota") { + let quota = match parse_job_quota(quota) { + Ok(q) => q, + Err(msg) => return Ok(jerr(400, msg)), + }; + update.job_quota = Some(quota); + detail.insert("job_quota".into(), json!(quota)); + } + if detail.is_empty() { + return Ok(jerr(400, "nothing to update")); + } + let detail = Value::Object(detail); + let out = + self.db(|c| store::operator_update_org(c, id, &update, reason.as_deref(), &detail))?; + Ok(match out { + store::Outcome::Done(()) => ok_true(), + _ => not_found(), + }) + } + + fn operator_org_lock(&self, id: i64) -> R { + let body = gate!(self.read_obj()); + let reason = gate!(reason_of(&body, LOCK_REASON_MIN)).unwrap_or_default(); + Ok( + match self.db(|c| store::operator_lock_org(c, id, &reason))? { + store::Outcome::Done(n) => { + Resp::json(200, &json!({ "ok": true, "cancelled_jobs": n })) + } + store::Outcome::Refused(_) => jerr(409, "org is already locked"), + store::Outcome::NotFound => not_found(), + }, + ) + } + + fn operator_org_unlock(&self, id: i64) -> R { + let body = gate!(self.read_obj()); + let reason = gate!(reason_of(&body, 0)); + Ok( + match self.db(|c| store::operator_unlock_org(c, id, reason.as_deref()))? { + store::Outcome::Done(()) => ok_true(), + store::Outcome::Refused(_) => jerr(409, "org is not locked"), + store::Outcome::NotFound => not_found(), + }, + ) + } + + fn operator_org_delete(&self, id: i64) -> R { + let body = gate!(self.read_obj()); + let reason = gate!(reason_of(&body, 1)).unwrap_or_default(); + let Some(Value::String(confirm)) = body.get("confirm") else { + return Ok(jerr(400, "confirm must be the org name")); + }; + let out = self.db(|c| store::operator_delete_org(c, id, confirm, &reason))?; + Ok(match out { + store::Outcome::Done(()) => { + // secure_delete zeroed the pages; this clears the WAL frames too. A reader can + // block it: logged, never a failed request (the org is gone either way). + self.db(|c| store::truncate_wal_logged(c, "operator delete org")); + ok_true() + } + store::Outcome::Refused(store::Refusal::DefaultOrg) => { + jerr(400, "the default org cannot be removed") + } + store::Outcome::Refused(_) => jerr(400, "confirm must be the org name"), + store::Outcome::NotFound => not_found(), + }) + } + + fn operator_org_create(&self) -> R { + let body = gate!(self.read_obj()); + let reason = gate!(reason_of(&body, 0)); + let name = gate!(name_of(body.get("name"), "name")); + let email = str_field(&body, "email") + .map(store::normalize_email) + .unwrap_or_default(); + if !email.contains('@') { + return Ok(jerr(400, "email required")); + } + if !self.mail_ready() { + return Ok(jerr(409, "mail is not configured")); + } + // a hash of a random password, never a NULL one: login timing reveals nothing about the + // invited account, and nobody can log in before the invitation is used + let pw_hash = match auth::hash_password(Some(&auth::token_urlsafe(32))) { + Ok(h) => h, + Err(e) => return Ok(jerr(500, e)), + }; + let tok = auth::new_session_token(); + let ttl = self.cfg().reset_ttl_s; + let quota = self.cfg().signup_quota; + let new = match self.db(|c| { + store::operator_create_org( + c, + &name, + &email, + &pw_hash, + quota, + &tok, + ttl, + reason.as_deref(), + ) + }) { + Ok(n) => n, + Err(StoreError::Conflict) => return Ok(jerr(409, "email already registered")), + Err(e) => return Err(e), + }; + let text = self.reset_mail_text( + "You have been invited to printpapi. Choose a password with the link below.", + &tok, + ); + let row = store::AuditRow { + org_id: Some(new.org_id), + target: Some(&format!("user:{}", new.user_id)), + ..Default::default() + }; + let sent = self.send_operator_mail(&email, "Your printpapi invitation", &text, &row); + Ok(Resp::json( + 200, + &json!({ "ok": true, "org_id": new.org_id, "user_id": new.user_id, "mail_sent": sent }), + )) + } + + fn operator_user_reset(&self, user_id: i64) -> R { + let body = gate!(self.read_obj()); + let org_id = gate!(org_id_of(&body)); + let reason = gate!(reason_of(&body, 0)); + if !self.mail_ready() { + return Ok(jerr(409, "mail is not configured")); + } + let tok = auth::new_session_token(); + let ttl = self.cfg().reset_ttl_s; + let out = self + .db(|c| store::operator_reset_user(c, user_id, org_id, &tok, ttl, reason.as_deref()))?; + let email = match out { + store::Outcome::Done(e) => e, + store::Outcome::Refused(_) => return Ok(jerr(409, "user belongs to another org")), + store::Outcome::NotFound => return Ok(not_found()), + }; + let text = self.reset_mail_text( + "An operator started a password reset for your printpapi account.", + &tok, + ); + let row = store::AuditRow { + org_id: Some(org_id), + target: Some(&format!("user:{user_id}")), + ..Default::default() + }; + if self.send_operator_mail(&email, "Reset your printpapi password", &text, &row) { + Ok(ok_true()) + } else { + Ok(jerr(502, "mail could not be sent")) + } + } + + fn operator_key_revoke(&self, key_id: i64) -> R { + let body = gate!(self.read_obj()); + let org_id = gate!(org_id_of(&body)); + let reason = gate!(reason_of(&body, 0)); + let out = self.db(|c| store::operator_revoke_key(c, key_id, org_id, reason.as_deref()))?; + Ok(match out { + store::Outcome::Done(()) => { + // a long-poll of an agent enrolled with this key re-checks it and ends with 401 + self.s.waker.wake_all(); + ok_true() + } + store::Outcome::Refused(_) => jerr(409, "key belongs to another org"), + store::Outcome::NotFound => not_found(), + }) + } + fn operator_orgs(&self) -> R { let (limit, after) = gate!(self.paging("after")); let q = query_params(self.target()); diff --git a/crates/server/src/store.rs b/crates/server/src/store.rs index 258d642..f650053 100644 --- a/crates/server/src/store.rs +++ b/crates/server/src/store.rs @@ -52,6 +52,8 @@ pub enum StoreError { Invalid(String), /// A UNIQUE/NOT NULL violation (the Python `sqlite3.IntegrityError`) — callers map it to 409. Conflict, + /// The org is locked by the operator — the server answers 403 `org locked`. + Locked, Db(rusqlite::Error), } @@ -63,6 +65,7 @@ impl std::fmt::Display for StoreError { | StoreError::Auth(m) | StoreError::Invalid(m) => f.write_str(m), StoreError::Conflict => f.write_str("constraint violation"), + StoreError::Locked => f.write_str("org locked"), StoreError::Db(e) => write!(f, "database error: {e}"), } } @@ -841,6 +844,7 @@ pub fn delete_org_tx(tx: &Transaction, org_id: i64) -> Result { "users", "label_templates", "terms_acceptances", + "org_locks", ] { tx.execute(&format!("DELETE FROM {table} WHERE org_id=?"), [org_id])?; } @@ -1440,6 +1444,20 @@ pub fn get_printer( .optional()?) } +/// `Locked` while the operator has locked `org_id`. A pure flag: quota and plan are not looked at. +/// Checked next to `check_quota` wherever a job may enter, and before any payload is fetched. +pub fn check_not_locked(conn: &Connection, org_id: i64) -> Result<()> { + let locked = conn + .prepare_cached("SELECT 1 FROM org_locks WHERE org_id=?")? + .query_row([org_id], |_| Ok(())) + .optional()? + .is_some(); + if locked { + return Err(StoreError::Locked); + } + Ok(()) +} + /// `QuotaExceeded` once `org_id` has used up its monthly quota. pub fn check_quota(conn: &Connection, org_id: i64, now: f64) -> Result<()> { let quota: Option = conn @@ -1498,6 +1516,8 @@ pub fn enqueue_job(conn: &Connection, job: &NewJob<'_>) -> Result { let Some((org_id, agent_id)) = printer else { return Err(unknown()); }; + // before the idempotency lookup: a locked org gets no job, not even an old one back + check_not_locked(&tx, org_id)?; if let Some(key) = &job.idempotency_key { // A retried submit returns the original job — the same key never prints twice in an org. // The lookup is safe under the write transaction; the UNIQUE index enforces it. @@ -2273,7 +2293,10 @@ pub fn insert_audit(tx: &Transaction, row: &AuditRow) -> Result { row.reason, row.detail ], - )?; + ) + // never a Conflict: no caller can have a unique violation here, and a refused audit insert + // must not read as "e-mail already registered" + .map_err(StoreError::Db)?; Ok(tx.last_insert_rowid()) } @@ -2312,6 +2335,288 @@ pub fn list_audit( Ok(rows.collect::>()?) } +// --- operator writes ------------------------------------------------------------------------------- +// +// Each action is one function: one `BEGIN IMMEDIATE`, the change, its audit row, one commit. A +// refused or failed action drops the transaction, so neither the change nor the row is kept. Audit +// content is ids and numbers only (never an e-mail address, a name or a title). Mail and the WAL +// truncate belong to the caller and run after the commit. + +/// What an operator action came to when it did not fail. +#[derive(Debug, PartialEq)] +pub enum Outcome { + Done(T), + NotFound, + Refused(Refusal), +} + +/// Why an operator action was not carried out although the thing exists. +#[derive(Debug, Clone, Copy, PartialEq)] +pub enum Refusal { + AlreadyLocked, + NotLocked, + /// The id belongs to another org than the caller named (a stale page, a reused id). + OrgMismatch, + /// The typed name is not the org's current name. + ConfirmMismatch, + DefaultOrg, +} + +/// When the org was created: what keeps a reused org id apart in the audit log. +fn org_created_at(tx: &Transaction, org_id: i64) -> Result> { + Ok(tx + .query_row("SELECT created_at FROM orgs WHERE id=?", [org_id], |r| { + r.get(0) + }) + .optional()?) +} + +/// `org.update`: every set field of `u` in one transaction. `detail` says which fields (no name). +pub fn operator_update_org( + conn: &Connection, + org_id: i64, + u: &OrgUpdate, + reason: Option<&str>, + detail: &Value, +) -> Result> { + let tx = begin(conn)?; + let Some(created) = org_created_at(&tx, org_id)? else { + return Ok(Outcome::NotFound); + }; + update_org_tx(&tx, org_id, u)?; + insert_audit( + &tx, + &AuditRow { + action: "org.update", + org_id: Some(org_id), + org_created_at: Some(created), + reason, + detail: Some(&detail.to_string()), + ..Default::default() + }, + )?; + tx.commit()?; + Ok(Outcome::Done(())) +} + +/// `org.lock`: the flag row, and the org's queued jobs cancelled (`error: "org locked"`). Returns +/// how many. Claimed jobs run on; quota and plan stay as they are. +pub fn operator_lock_org(conn: &Connection, org_id: i64, reason: &str) -> Result> { + let tx = begin(conn)?; + let Some(created) = org_created_at(&tx, org_id)? else { + return Ok(Outcome::NotFound); + }; + let now = crate::now(); + let inserted = tx.execute( + "INSERT OR IGNORE INTO org_locks(org_id, org_created_at, reason, locked_at) VALUES(?,?,?,?)", + params![org_id, created, reason, now], + )?; + if inserted == 0 { + return Ok(Outcome::Refused(Refusal::AlreadyLocked)); + } + let cancelled = tx.execute( + "UPDATE jobs SET state='cancelled', error='org locked', finished_at=? \ + WHERE org_id=? AND state='queued'", + params![now, org_id], + )? as i64; + insert_audit( + &tx, + &AuditRow { + action: "org.lock", + org_id: Some(org_id), + org_created_at: Some(created), + reason: Some(reason), + detail: Some(&serde_json::json!({ "cancelled_jobs": cancelled }).to_string()), + ..Default::default() + }, + )?; + tx.commit()?; + Ok(Outcome::Done(cancelled)) +} + +/// `org.unlock`: the flag row removed. +pub fn operator_unlock_org( + conn: &Connection, + org_id: i64, + reason: Option<&str>, +) -> Result> { + let tx = begin(conn)?; + let Some(created) = org_created_at(&tx, org_id)? else { + return Ok(Outcome::NotFound); + }; + if tx.execute("DELETE FROM org_locks WHERE org_id=?", [org_id])? == 0 { + return Ok(Outcome::Refused(Refusal::NotLocked)); + } + insert_audit( + &tx, + &AuditRow { + action: "org.unlock", + org_id: Some(org_id), + org_created_at: Some(created), + reason, + ..Default::default() + }, + )?; + tx.commit()?; + Ok(Outcome::Done(())) +} + +/// `org.delete`: `confirm` must be the org's current name; the default org is never removed. The +/// audit rows of the org stay (they hold no name). +pub fn operator_delete_org( + conn: &Connection, + org_id: i64, + confirm: &str, + reason: &str, +) -> Result> { + if org_id == DEFAULT_ORG { + return Ok(Outcome::Refused(Refusal::DefaultOrg)); + } + let tx = begin(conn)?; + let found: Option<(String, f64)> = tx + .query_row( + "SELECT name, created_at FROM orgs WHERE id=?", + [org_id], + |r| Ok((r.get(0)?, r.get(1)?)), + ) + .optional()?; + let Some((name, created)) = found else { + return Ok(Outcome::NotFound); + }; + if name != confirm { + return Ok(Outcome::Refused(Refusal::ConfirmMismatch)); + } + delete_org_tx(&tx, org_id)?; + insert_audit( + &tx, + &AuditRow { + action: "org.delete", + org_id: Some(org_id), + org_created_at: Some(created), + reason: Some(reason), + ..Default::default() + }, + )?; + tx.commit()?; + Ok(Outcome::Done(())) +} + +/// `org.create`: a new org, its first user and the invitation token in one transaction. +/// Err(Conflict) if the e-mail is taken (the rollback takes the half-made org along). +#[allow(clippy::too_many_arguments)] +pub fn operator_create_org( + conn: &Connection, + org_name: &str, + email: &str, + password_hash: &str, + job_quota: Option, + invite_token: &str, + invite_ttl_s: f64, + reason: Option<&str>, +) -> Result { + let tx = begin(conn)?; + let new = signup_tx(&tx, org_name, email, password_hash, job_quota, None)?; + // the invitation is a reset token, minted in the same transaction as the account it opens + create_password_reset_tx(&tx, new.user_id, invite_token, invite_ttl_s, None)?; + insert_audit( + &tx, + &AuditRow { + action: "org.create", + org_id: Some(new.org_id), + org_created_at: org_created_at(&tx, new.org_id)?, + target: Some(&format!("user:{}", new.user_id)), + reason, + detail: Some(&serde_json::json!({ "job_quota": job_quota }).to_string()), + }, + )?; + tx.commit()?; + Ok(new) +} + +/// `user.reset`: mint the reset token. Returns the user's e-mail address for the mail the caller +/// sends after the commit. `org_id` must be the user's org; a user without an address (the seeded +/// legacy one) is not found. +pub fn operator_reset_user( + conn: &Connection, + user_id: i64, + org_id: i64, + token: &str, + ttl_s: f64, + reason: Option<&str>, +) -> Result> { + let tx = begin(conn)?; + let user: Option<(i64, Option)> = tx + .query_row( + "SELECT org_id, email FROM users WHERE id=?", + [user_id], + |r| Ok((r.get(0)?, r.get(1)?)), + ) + .optional()?; + let Some((owner, Some(email))) = user else { + return Ok(Outcome::NotFound); + }; + if owner != org_id { + return Ok(Outcome::Refused(Refusal::OrgMismatch)); + } + create_password_reset_tx(&tx, user_id, token, ttl_s, None)?; + insert_audit( + &tx, + &AuditRow { + action: "user.reset", + org_id: Some(org_id), + org_created_at: org_created_at(&tx, org_id)?, + target: Some(&format!("user:{user_id}")), + reason, + ..Default::default() + }, + )?; + tx.commit()?; + Ok(Outcome::Done(email)) +} + +/// A row of its own, for what happens after a commit (a reset mail that did not go out). +pub fn operator_audit_note(conn: &Connection, row: &AuditRow) -> Result { + let tx = begin(conn)?; + let id = insert_audit(&tx, row)?; + tx.commit()?; + Ok(id) +} + +/// `key.revoke`: `org_id` must be the key's org. +pub fn operator_revoke_key( + conn: &Connection, + key_id: i64, + org_id: i64, + reason: Option<&str>, +) -> Result> { + let tx = begin(conn)?; + let owner: Option = tx + .query_row("SELECT org_id FROM api_keys WHERE id=?", [key_id], |r| { + r.get(0) + }) + .optional()?; + let Some(owner) = owner else { + return Ok(Outcome::NotFound); + }; + if owner != org_id { + return Ok(Outcome::Refused(Refusal::OrgMismatch)); + } + revoke_api_key_tx(&tx, key_id, Some(org_id))?; + insert_audit( + &tx, + &AuditRow { + action: "key.revoke", + org_id: Some(org_id), + org_created_at: org_created_at(&tx, org_id)?, + target: Some(&format!("key:{key_id}")), + reason, + ..Default::default() + }, + )?; + tx.commit()?; + Ok(Outcome::Done(())) +} + // --- operator reads: orgs and their jobs -------------------------------------------------------- // // Metadata only. None of these statements selects a payload, title, callback URL, idempotency diff --git a/crates/server/tests/http_operator.rs b/crates/server/tests/http_operator.rs index fd01e80..87aa411 100644 --- a/crates/server/tests/http_operator.rs +++ b/crates/server/tests/http_operator.rs @@ -654,7 +654,10 @@ fn org_read_endpoints_need_the_gate_and_are_get_only() { 401, "{t}" ); - assert_eq!(op(&app, "DELETE", t).send().status, 404, "DELETE {t}"); + // /operator/orgs/{id} has writes of its own now; the list and the jobs stay read-only + if t != "/operator/orgs/1" { + assert_eq!(op(&app, "DELETE", t).send().status, 404, "DELETE {t}"); + } } let r = op(&app, "GET", "/operator/orgs").send(); assert_eq!(r.status, 200, "{}", r.text()); diff --git a/crates/server/tests/http_operator_writes.rs b/crates/server/tests/http_operator_writes.rs new file mode 100644 index 0000000..c95b218 --- /dev/null +++ b/crates/server/tests/http_operator_writes.rs @@ -0,0 +1,1291 @@ +// printpapi — self-hosted PrintNode alternative. Elastic License 2.0 (see LICENSE). +//! The operator's write endpoints: org update, lock and unlock, delete, create with an invitation, +//! reset mail and key revoke. Each is one store function and one transaction with its audit row. +mod common; + +use base64::{Engine, engine::general_purpose::STANDARD as B64}; +use common::*; +use hmac::{Hmac, KeyInit, Mac}; +use printpapi_server::billing; +use printpapi_server::proxy::TrustedProxies; +use printpapi_server::server::Config; +use printpapi_server::store::{self, Db}; +use serde_json::{Value, json}; +use sha2::Sha256; + +const OP: &str = "operator-token-0123456789abcdef-xyz"; +const CONSOLE: &str = "10.9.0.2"; +const REASON: &str = "support ticket 4711"; + +fn hosted_cfg(c: &mut Config) { + c.operator_token = Some(OP.into()); + c.operator_from = TrustedProxies::parse(CONSOLE).unwrap(); +} + +/// Hosted, with mail and a public URL (so reset mails and invitations work), a signup quota and a +/// plan catalogue. +fn mail_cfg(c: &mut Config) { + hosted_cfg(c); + c.reset_enabled = true; + c.public_url = "https://print.example".into(); + c.signup_quota = Some(25); + c.plans = billing::load_plans( + &json!([ + {"id": "free", "name": "Free", "jobs": 50, "price": "0 EUR"}, + {"id": "pro", "name": "Pro", "jobs": 5000, "price": "9 EUR/mo"}, + ]) + .to_string(), + ) + .unwrap(); +} + +fn app() -> App { + App::with(mail_cfg) +} + +fn op<'a>(app: &'a App, method: &str, target: &str) -> Call<'a> { + app.call(method, target).bearer(OP).socket(CONSOLE) +} + +fn send(app: &App, method: &str, target: &str, body: Value) -> (u16, Value) { + let r = op(app, method, target).json(&body).send(); + (r.status, r.json()) +} + +fn sql(db: &Db, q: &str, p: impl rusqlite::Params) { + db.with(|c| c.execute(q, p).unwrap()); +} + +fn count(db: &Db, q: &str, p: impl rusqlite::Params) -> i64 { + db.with(|c| c.query_row(q, p, |r| r.get(0)).unwrap()) +} + +/// An org with one user, as a signup makes one. Returns (org id, user id). +fn customer(db: &Db, name: &str, email: &str) -> (i64, i64) { + let s = db + .with(|c| store::signup(c, name, email, "PWHASHSENTINEL", Some(100), None)) + .unwrap(); + (s.org_id, s.user_id) +} + +/// A printer of `org` plus a client key `key-`: (printer id, key). +fn printer_and_key(db: &Db, org: i64) -> (i64, String) { + let reg = register( + db, + &format!("pc{org}"), + &format!("agent-key-{org}"), + &[decl("HP", true)], + org, + ); + let key = format!("key-{org}"); + add_key(db, "k", &key, org); + (reg.pid("HP"), key) +} + +fn audit_rows(app: &App) -> Vec { + let r = op(app, "GET", "/operator/audit?limit=200").send(); + assert_eq!(r.status, 200, "{}", r.text()); + r.json()["entries"].as_array().unwrap().clone() +} + +fn audit_of<'a>(rows: &'a [Value], action: &str) -> Vec<&'a Value> { + rows.iter().filter(|r| r["action"] == action).collect() +} + +fn org_name(db: &Db, org: i64) -> Option { + db.with(|c| store::get_org(c, org)).unwrap().map(|o| o.name) +} + +fn quota(db: &Db, org: i64) -> Option { + db.with(|c| store::get_org(c, org)) + .unwrap() + .unwrap() + .job_quota +} + +fn state_of(db: &Db, job: i64) -> (String, Option) { + db.with(|c| { + c.query_row("SELECT state, error FROM jobs WHERE id=?", [job], |r| { + Ok((r.get(0)?, r.get(1)?)) + }) + .unwrap() + }) +} + +// --- the gate ----------------------------------------------------------------------------------- + +#[test] +fn every_write_needs_the_gate_and_root_is_refused() { + let app = app(); + let (org, user) = customer(&app.db, "Acme", "boss@acme.test"); + let calls = [ + ("PUT", format!("/operator/orgs/{org}")), + ("POST", "/operator/orgs".to_string()), + ("POST", format!("/operator/orgs/{org}/lock")), + ("POST", format!("/operator/orgs/{org}/unlock")), + ("DELETE", format!("/operator/orgs/{org}")), + ("POST", format!("/operator/users/{user}/reset")), + ("DELETE", "/operator/keys/1".to_string()), + ]; + for (m, p) in &calls { + let r = app.call(m, p).socket(CONSOLE).json(&json!({})).send(); + assert_eq!(r.status, 401, "{m} {p} without a token"); + let r = app + .call(m, p) + .bearer("t") + .socket(CONSOLE) + .json(&json!({})) + .send(); + assert_eq!(r.status, 401, "{m} {p} with root"); + let r = app + .call(m, p) + .bearer(OP) + .socket("127.0.0.1") + .json(&json!({})) + .send(); + assert_eq!(r.status, 401, "{m} {p} from another peer"); + } + // and without a token configured they do not exist + let plain = App::new(); + for (m, p) in &calls { + assert_eq!(plain.call(m, p).bearer(OP).send().status, 404, "{m} {p}"); + } + // nothing changed + assert_eq!(org_name(&app.db, org).as_deref(), Some("Acme")); + assert!(audit_rows(&app).is_empty()); +} + +#[test] +fn a_write_answers_404_for_the_wrong_method() { + let app = app(); + let (org, _) = customer(&app.db, "Acme", "boss@acme.test"); + for (m, p) in [ + ("GET", format!("/operator/orgs/{org}/lock")), + ("PUT", format!("/operator/orgs/{org}/lock")), + ("DELETE", format!("/operator/orgs/{org}/jobs")), + ("POST", format!("/operator/orgs/{org}")), + ("GET", "/operator/keys/1".to_string()), + ("POST", "/operator/keys/1".to_string()), + ("GET", "/operator/users/1/reset".to_string()), + ] { + assert_eq!( + op(&app, m, &p).json(&json!({})).send().status, + 404, + "{m} {p}" + ); + } +} + +// --- PUT /operator/orgs/{id} --------------------------------------------------------------------- + +#[test] +fn put_org_updates_name_quota_and_plan_in_one_go() { + let app = app(); + let (org, _) = customer(&app.db, "Acme", "boss@acme.test"); + let created: f64 = app.db.with(|c| { + c.query_row("SELECT created_at FROM orgs WHERE id=?", [org], |r| { + r.get(0) + }) + .unwrap() + }); + let (st, v) = send( + &app, + "PUT", + &format!("/operator/orgs/{org}"), + json!({"name": "Acme Print", "plan": "pro", "reason": REASON}), + ); + assert_eq!(st, 200, "{v}"); + assert_eq!(v["ok"], true); + assert_eq!(org_name(&app.db, org).as_deref(), Some("Acme Print")); + assert_eq!(quota(&app.db, org), Some(5000)); + let plan: Option = app.db.with(|c| { + c.query_row("SELECT plan FROM orgs WHERE id=?", [org], |r| r.get(0)) + .unwrap() + }); + assert_eq!(plan.as_deref(), Some("pro")); + + // an explicit quota wins over the plan's and null means unlimited + let (st, _) = send( + &app, + "PUT", + &format!("/operator/orgs/{org}"), + json!({"job_quota": null}), + ); + assert_eq!(st, 200); + assert_eq!(quota(&app.db, org), None); + let (st, _) = send( + &app, + "PUT", + &format!("/operator/orgs/{org}"), + json!({"plan": "free", "job_quota": 7}), + ); + assert_eq!(st, 200); + assert_eq!(quota(&app.db, org), Some(7)); + + // one audit row per call, with ids, numbers and the reason, never the name + let rows = audit_rows(&app); + let rows = audit_of(&rows, "org.update"); + assert_eq!(rows.len(), 3); + let first = rows.last().unwrap(); + assert_eq!(first["actor"], "operator"); + assert_eq!(first["org_id"], org); + assert_eq!(first["org_created_at"], created); + assert_eq!(first["reason"], REASON); + assert_eq!(first["detail"]["plan"], "pro"); + assert!(!first.to_string().contains("Acme")); +} + +#[test] +fn put_org_validates_everything_before_it_writes_anything() { + let app = app(); + let (org, _) = customer(&app.db, "Acme", "boss@acme.test"); + for body in [ + json!({"name": "New", "plan": "nonsense"}), + json!({"name": "New", "job_quota": -1}), + json!({"name": "New", "job_quota": "ten"}), + json!({"name": ""}), + json!({"name": " "}), + json!({"name": 7}), + json!({"name": "x".repeat(201)}), + json!({"reason": "y".repeat(501), "name": "New"}), + json!({"reason": 5, "name": "New"}), + ] { + let (st, v) = send(&app, "PUT", &format!("/operator/orgs/{org}"), body.clone()); + assert_eq!(st, 400, "{body} -> {v}"); + } + assert_eq!(org_name(&app.db, org).as_deref(), Some("Acme")); + assert_eq!(quota(&app.db, org), Some(100)); + // nothing to update + let (st, _) = send(&app, "PUT", &format!("/operator/orgs/{org}"), json!({})); + assert_eq!(st, 400); + let (st, _) = send( + &app, + "PUT", + &format!("/operator/orgs/{org}"), + json!({"reason": REASON}), + ); + assert_eq!(st, 400); + // not JSON + let r = op(&app, "PUT", &format!("/operator/orgs/{org}")) + .raw(b"[1,2]") + .send(); + assert_eq!(r.status, 400); + assert!(audit_rows(&app).is_empty()); +} + +#[test] +fn put_org_of_an_unknown_org_is_404_and_writes_no_audit_row() { + let app = app(); + let (st, _) = send(&app, "PUT", "/operator/orgs/999", json!({"name": "x"})); + assert_eq!(st, 404); + assert!(audit_rows(&app).is_empty()); +} + +#[test] +fn put_org_does_not_touch_a_lock() { + let app = app(); + let (org, _) = customer(&app.db, "Acme", "boss@acme.test"); + assert_eq!( + send( + &app, + "POST", + &format!("/operator/orgs/{org}/lock"), + json!({"reason": REASON}) + ) + .0, + 200 + ); + let (st, _) = send( + &app, + "PUT", + &format!("/operator/orgs/{org}"), + json!({"job_quota": 3}), + ); + assert_eq!(st, 200); + assert_eq!(count(&app.db, "SELECT COUNT(*) FROM org_locks", []), 1); +} + +// --- lock and unlock ------------------------------------------------------------------------------ + +#[test] +fn lock_inserts_the_row_cancels_queued_jobs_and_leaves_the_quota_alone() { + let app = app(); + let (org, _) = customer(&app.db, "Acme", "boss@acme.test"); + let (other, _) = customer(&app.db, "Other", "o@other.test"); + let (pid, _) = printer_and_key(&app.db, org); + let (opid, _) = printer_and_key(&app.db, other); + let flying = enqueue(&app.db, pid, b"A", |j| j.org_id = Some(org)); + let waiting = enqueue(&app.db, pid, b"B", |j| j.org_id = Some(org)); + let agent = app + .db + .with(|c| store::authenticate_agent(c, &format!("agent-key-{org}"))) + .unwrap() + .unwrap(); + // claim takes the oldest queued job, so A is in flight and B still waits + claim(&app.db, agent).unwrap(); + let theirs = enqueue(&app.db, opid, b"C", |j| j.org_id = Some(other)); + + let (st, v) = send( + &app, + "POST", + &format!("/operator/orgs/{org}/lock"), + json!({"reason": REASON}), + ); + assert_eq!(st, 200, "{v}"); + assert_eq!(v["ok"], true); + assert_eq!(v["cancelled_jobs"], 1); + assert_eq!(state_of(&app.db, flying).0, "claimed"); + assert_eq!( + state_of(&app.db, waiting), + ("cancelled".into(), Some("org locked".into())) + ); + assert_eq!(state_of(&app.db, theirs).0, "queued"); + assert_eq!(quota(&app.db, org), Some(100)); + + // the detail and the list say so + let (_, d) = { + let r = op(&app, "GET", &format!("/operator/orgs/{org}")).send(); + (r.status, r.json()) + }; + assert_eq!(d["locked"], true); + assert_eq!(d["status"], "locked"); + assert_eq!(d["lock"]["reason"], REASON); + assert_eq!(d["job_quota"], 100); + + let rows = audit_rows(&app); + let rows = audit_of(&rows, "org.lock"); + assert_eq!(rows.len(), 1); + assert_eq!(rows[0]["org_id"], org); + assert_eq!(rows[0]["reason"], REASON); + assert_eq!(rows[0]["detail"]["cancelled_jobs"], 1); + let lock_created: f64 = app.db.with(|c| { + c.query_row( + "SELECT org_created_at FROM org_locks WHERE org_id=?", + [org], + |r| r.get(0), + ) + .unwrap() + }); + assert_eq!(rows[0]["org_created_at"], lock_created); +} + +#[test] +fn lock_needs_a_reason_of_eight_characters_and_an_existing_unlocked_org() { + let app = app(); + let (org, _) = customer(&app.db, "Acme", "boss@acme.test"); + for body in [ + json!({}), + json!({"reason": "short"}), + json!({"reason": 12345678}), + ] { + let (st, _) = send(&app, "POST", &format!("/operator/orgs/{org}/lock"), body); + assert_eq!(st, 400); + } + assert_eq!(count(&app.db, "SELECT COUNT(*) FROM org_locks", []), 0); + let (st, _) = send( + &app, + "POST", + "/operator/orgs/999/lock", + json!({"reason": REASON}), + ); + assert_eq!(st, 404); + let (st, _) = send( + &app, + "POST", + &format!("/operator/orgs/{org}/lock"), + json!({"reason": REASON}), + ); + assert_eq!(st, 200); + let (st, _) = send( + &app, + "POST", + &format!("/operator/orgs/{org}/lock"), + json!({"reason": REASON}), + ); + assert_eq!(st, 409); + // only the one successful lock left a row + assert_eq!(audit_rows(&app).len(), 1); +} + +fn shopify_post(app: &App, target: &str, secret: &str) -> u16 { + let body = json!({"id": 450789469, "order_number": 1001, "name": "#1001", + "line_items": [{"quantity": 1, "sku": "A", "title": "W", "price": "1.00"}]}); + let data = serde_json::to_vec(&body).unwrap(); + let digest = B64.encode( + Hmac::::new_from_slice(secret.as_bytes()) + .unwrap() + .chain_update(&data) + .finalize() + .into_bytes(), + ); + app.call("POST", target) + .header("content-type", "application/json") + .header("x-shopify-hmac-sha256", &digest) + .header("x-shopify-shop-domain", "acme.myshopify.com") + .raw(&data) + .send() + .status +} + +/// The four ways a job gets in, each as a customer of `org` would use them. Returns the statuses +/// and bodies in the order POST /jobs, POST /orders, Shopify webhook, PrintNode POST /printjobs. +fn submit_everywhere(app: &App, org: i64, pid: i64, key: &str, n: u32) -> [(u16, Value); 4] { + let (c1, b1) = app.post( + "/jobs", + Some(key), + json!({"printer_id": pid, "type": "raw_base64", "content": "QUJD", + "idempotency_key": format!("j{n}")}), + ); + let (c2, b2) = app.post( + "/orders", + Some(key), + json!({"printer_id": pid, "order": {"number": format!("{n}"), "customer": "J", + "address": ["x"], "lines": [{"qty": 1, "sku": "A", "name": "W", "total": "1"}], + "totals": [["Total", "1"]]}}), + ); + app.db + .with(|c| store::set_org_shopify_secret(c, org, Some("s3cret"))) + .unwrap(); + let hook = format!("/integrations/shopify/orders?key={key}&printer_id={pid}"); + let c3 = shopify_post(app, &hook, "s3cret"); + let (c4, b4) = app.pn( + "POST", + "/printjobs", + key, + Some( + json!({"printerId": pid, "title": "L", "contentType": "raw_base64", "content": "QUJD"}), + ), + ); + [(c1, b1), (c2, b2), (c3, Value::Null), (c4, b4)] +} + +#[test] +fn nothing_changes_for_an_org_without_a_lock_row() { + let app = app(); + let (org, _) = customer(&app.db, "Acme", "boss@acme.test"); + let (other, _) = customer(&app.db, "Other", "o@other.test"); + let (pid, key) = printer_and_key(&app.db, org); + // someone else's lock does not reach this org + assert_eq!( + send( + &app, + "POST", + &format!("/operator/orgs/{other}/lock"), + json!({"reason": REASON}) + ) + .0, + 200 + ); + let r = submit_everywhere(&app, org, pid, &key, 1); + assert_eq!(r[0].0, 200, "{:?}", r[0]); + assert_eq!(r[1].0, 200, "{:?}", r[1]); + assert_eq!(r[2], (200, Value::Null)); + assert_eq!(r[3].0, 201, "{:?}", r[3]); + assert_eq!(count(&app.db, "SELECT COUNT(*) FROM jobs", []), 4); +} + +#[test] +fn a_locked_org_is_refused_on_every_submit_path_with_403() { + let app = app(); + let (org, _) = customer(&app.db, "Acme", "boss@acme.test"); + let (pid, key) = printer_and_key(&app.db, org); + assert_eq!( + send( + &app, + "POST", + &format!("/operator/orgs/{org}/lock"), + json!({"reason": REASON}) + ) + .0, + 200 + ); + let r = submit_everywhere(&app, org, pid, &key, 1); + assert_eq!( + (r[0].0, r[0].1["error"].as_str()), + (403, Some("org locked")), + "POST /jobs" + ); + assert_eq!( + (r[1].0, r[1].1["error"].as_str()), + (403, Some("org locked")), + "POST /orders" + ); + assert_eq!(r[2].0, 403, "the Shopify webhook"); + assert_eq!(r[3].0, 403, "PrintNode POST /printjobs"); + assert!(r[3].1.to_string().contains("org locked"), "{}", r[3].1); + assert_eq!(count(&app.db, "SELECT COUNT(*) FROM jobs", []), 0); + + // the same with a session instead of a key, and root naming the org's printer + let session = app.account(org, "second@acme.test"); + let (st, _) = app.post( + "/jobs", + Some(&session), + json!({"printer_id": pid, "type": "raw_base64", "content": "QUJD"}), + ); + assert_eq!(st, 403); + let (st, _) = app.post( + "/jobs", + Some("t"), + json!({"printer_id": pid, "type": "raw_base64", "content": "QUJD"}), + ); + assert_eq!(st, 403); + // an idempotent resubmit does not slip past the lock either + assert_eq!(count(&app.db, "SELECT COUNT(*) FROM jobs", []), 0); + + // logins, the dashboard's reads and the agent keep working, so the customer can see why + let (st, _) = app.get("/jobs", Some(&session)); + assert_eq!(st, 200); + let (st, _) = app.login("second@acme.test", PW); + assert_eq!(st, 200); + let r = app.agent("GET", "/agent/jobs", &format!("agent-key-{org}"), None); + assert_ne!(r.status, 401); + assert_ne!(r.status, 403); +} + +#[test] +fn the_lock_is_checked_before_a_payload_is_fetched() { + let app = app(); + app.fetch.gets.lock().unwrap().clear(); + let (org, _) = customer(&app.db, "Acme", "boss@acme.test"); + let (pid, key) = printer_and_key(&app.db, org); + send( + &app, + "POST", + &format!("/operator/orgs/{org}/lock"), + json!({"reason": REASON}), + ); + let (st, v) = app.post( + "/jobs", + Some(&key), + json!({"printer_id": pid, "type": "raw_uri", "url": "https://files.example/a.zpl"}), + ); + assert_eq!((st, v["error"].as_str()), (403, Some("org locked"))); + assert!( + app.fetch.gets.lock().unwrap().is_empty(), + "fetched for a locked org" + ); +} + +#[test] +fn unlock_deletes_the_row_and_submits_work_again() { + let app = app(); + let (org, _) = customer(&app.db, "Acme", "boss@acme.test"); + let (pid, key) = printer_and_key(&app.db, org); + // not locked: 409; unknown org: 404 + let (st, _) = send( + &app, + "POST", + &format!("/operator/orgs/{org}/unlock"), + json!({}), + ); + assert_eq!(st, 409); + let (st, _) = send(&app, "POST", "/operator/orgs/999/unlock", json!({})); + assert_eq!(st, 404); + send( + &app, + "POST", + &format!("/operator/orgs/{org}/lock"), + json!({"reason": REASON}), + ); + assert_eq!( + app.post( + "/jobs", + Some(&key), + json!({"printer_id": pid, "type": "raw_base64", "content": "QUJD"}) + ) + .0, + 403 + ); + let (st, v) = send( + &app, + "POST", + &format!("/operator/orgs/{org}/unlock"), + json!({"reason": "paid the invoice"}), + ); + assert_eq!(st, 200, "{v}"); + assert_eq!(count(&app.db, "SELECT COUNT(*) FROM org_locks", []), 0); + let r = submit_everywhere(&app, org, pid, &key, 1); + assert_eq!([r[0].0, r[1].0, r[2].0, r[3].0], [200, 200, 200, 201]); + let rows = audit_rows(&app); + let unlocks = audit_of(&rows, "org.unlock"); + assert_eq!(unlocks.len(), 1); + assert_eq!(unlocks[0]["reason"], "paid the invoice"); + assert_eq!(unlocks[0]["org_id"], org); + // the reason is optional + send( + &app, + "POST", + &format!("/operator/orgs/{org}/lock"), + json!({"reason": REASON}), + ); + let (st, _) = send( + &app, + "POST", + &format!("/operator/orgs/{org}/unlock"), + json!({}), + ); + assert_eq!(st, 200); +} + +// --- DELETE /operator/orgs/{id} ------------------------------------------------------------------- + +#[test] +fn delete_needs_the_exact_name_and_a_reason() { + let app = app(); + let (org, _) = customer(&app.db, "Acme", "boss@acme.test"); + let path = format!("/operator/orgs/{org}"); + for body in [ + json!({"reason": REASON}), + json!({"reason": REASON, "confirm": "acme"}), + json!({"reason": REASON, "confirm": "Acme "}), + json!({"reason": REASON, "confirm": 7}), + json!({"confirm": "Acme"}), + json!({"reason": "", "confirm": "Acme"}), + ] { + let (st, v) = send(&app, "DELETE", &path, body.clone()); + assert_eq!(st, 400, "{body} -> {v}"); + } + assert!(org_name(&app.db, org).is_some()); + assert!(audit_rows(&app).is_empty()); + let (st, _) = send( + &app, + "DELETE", + "/operator/orgs/999", + json!({"reason": REASON, "confirm": "x"}), + ); + assert_eq!(st, 404); +} + +#[test] +fn delete_never_removes_the_default_org() { + let app = app(); + let name = org_name(&app.db, store::DEFAULT_ORG).unwrap(); + let (st, _) = send( + &app, + "DELETE", + &format!("/operator/orgs/{}", store::DEFAULT_ORG), + json!({"reason": REASON, "confirm": name}), + ); + assert_eq!(st, 400); + assert!(org_name(&app.db, store::DEFAULT_ORG).is_some()); +} + +#[test] +fn delete_removes_the_org_with_its_lock_and_keeps_the_audit_rows() { + let app = app(); + let (org, user) = customer(&app.db, "Acme", "boss@acme.test"); + let (pid, _) = printer_and_key(&app.db, org); + enqueue(&app.db, pid, b"A", |j| j.org_id = Some(org)); + let created: f64 = app.db.with(|c| { + c.query_row("SELECT created_at FROM orgs WHERE id=?", [org], |r| { + r.get(0) + }) + .unwrap() + }); + send( + &app, + "POST", + &format!("/operator/orgs/{org}/lock"), + json!({"reason": REASON}), + ); + let (st, v) = send( + &app, + "DELETE", + &format!("/operator/orgs/{org}"), + json!({"reason": "asked to be forgotten", "confirm": "Acme"}), + ); + assert_eq!(st, 200, "{v}"); + assert!(org_name(&app.db, org).is_none()); + assert_eq!(count(&app.db, "SELECT COUNT(*) FROM org_locks", []), 0); + assert_eq!( + count(&app.db, "SELECT COUNT(*) FROM jobs WHERE org_id=?", [org]), + 0 + ); + assert_eq!( + count(&app.db, "SELECT COUNT(*) FROM users WHERE id=?", [user]), + 0 + ); + // lock and delete rows are still there, the second one with the org's creation time + let rows = audit_rows(&app); + assert_eq!(audit_of(&rows, "org.lock").len(), 1); + let del = audit_of(&rows, "org.delete"); + assert_eq!(del.len(), 1); + assert_eq!(del[0]["org_id"], org); + assert_eq!(del[0]["org_created_at"], created); + assert_eq!(del[0]["reason"], "asked to be forgotten"); + assert!(!rows.iter().any(|r| r.to_string().contains("Acme"))); + // gone is gone + let (st, _) = send( + &app, + "DELETE", + &format!("/operator/orgs/{org}"), + json!({"reason": REASON, "confirm": "Acme"}), + ); + assert_eq!(st, 404); +} + +#[test] +fn root_deleting_an_org_removes_its_lock_row_too() { + // the legacy route shares delete_org: a lock must not outlive its org and bite the next one + // that reuses the id + let app = app(); + let (org, _) = customer(&app.db, "Acme", "boss@acme.test"); + send( + &app, + "POST", + &format!("/operator/orgs/{org}/lock"), + json!({"reason": REASON}), + ); + assert_eq!(count(&app.db, "SELECT COUNT(*) FROM org_locks", []), 1); + let (st, _) = app.delete(&format!("/orgs/{org}"), Some("t")); + assert_eq!(st, 200); + assert_eq!(count(&app.db, "SELECT COUNT(*) FROM org_locks", []), 0); +} + +// --- POST /operator/orgs -------------------------------------------------------------------------- + +#[test] +fn create_makes_the_org_and_its_first_user_and_mails_the_invitation() { + let app = app(); + let (st, v) = send( + &app, + "POST", + "/operator/orgs", + json!({"name": "Fresh GmbH", "email": " New@Fresh.Test ", "reason": "onboarding call"}), + ); + assert_eq!(st, 200, "{v}"); + let (org, user) = ( + v["org_id"].as_i64().unwrap(), + v["user_id"].as_i64().unwrap(), + ); + assert_eq!(org_name(&app.db, org).as_deref(), Some("Fresh GmbH")); + // the signup quota, as a self-signup would get + assert_eq!(quota(&app.db, org), Some(25)); + // a real hash of a random password, never a NULL one + let hash: Option = app.db.with(|c| { + c.query_row("SELECT password_hash FROM users WHERE id=?", [user], |r| { + r.get(0) + }) + .unwrap() + }); + let hash = hash.expect("a hash"); + assert!(hash.starts_with("scrypt$"), "{hash}"); + let email: String = app.db.with(|c| { + c.query_row("SELECT email FROM users WHERE id=?", [user], |r| r.get(0)) + .unwrap() + }); + assert_eq!(email, "new@fresh.test"); + // the invitation is the reset mail, and the token is in the mail only + let mails = app.mail.all(); + assert_eq!(mails.len(), 1); + assert_eq!(mails[0].to, "new@fresh.test"); + assert!( + mails[0].body.contains("https://print.example/?reset=sess_"), + "{}", + mails[0].body + ); + let tok = mails[0] + .body + .split("?reset=") + .nth(1) + .unwrap() + .split_whitespace() + .next() + .unwrap() + .to_string(); + assert!(!v.to_string().contains(&tok)); + // and it works: the invited person sets a password with it + let (st, _) = app.post( + "/password/reset/confirm", + None, + json!({"token": tok, "password": "a-new-password-1"}), + ); + assert_eq!(st, 200); + assert_eq!(app.login("new@fresh.test", "a-new-password-1").0, 200); + + let rows = audit_rows(&app); + let rows = audit_of(&rows, "org.create"); + assert_eq!(rows.len(), 1); + assert_eq!(rows[0]["org_id"], org); + assert_eq!(rows[0]["reason"], "onboarding call"); + assert!(rows[0]["org_created_at"].as_f64().unwrap() > 1.0e9); + let text = rows[0].to_string(); + assert!( + !text.contains("Fresh") && !text.contains("fresh.test"), + "{text}" + ); +} + +#[test] +fn create_without_mail_or_public_url_is_409_and_creates_nothing() { + for tweak in [ + (|c: &mut Config| { + hosted_cfg(c); + }) as fn(&mut Config), + |c: &mut Config| { + hosted_cfg(c); + c.reset_enabled = true; // mail, but no PUBLIC_URL + }, + |c: &mut Config| { + hosted_cfg(c); + c.public_url = "https://print.example".into(); // a URL, but no mail + }, + ] { + let app = App::with(tweak); + let before = count(&app.db, "SELECT COUNT(*) FROM orgs", []); + let (st, v) = send( + &app, + "POST", + "/operator/orgs", + json!({"name": "Fresh", "email": "new@fresh.test"}), + ); + assert_eq!( + (st, v["error"].as_str()), + (409, Some("mail is not configured")) + ); + assert_eq!(count(&app.db, "SELECT COUNT(*) FROM orgs", []), before); + assert!(app.mail.all().is_empty()); + assert!(audit_rows(&app).is_empty()); + } +} + +#[test] +fn create_rejects_bad_input_and_a_taken_email_and_leaves_nothing_behind() { + let app = app(); + customer(&app.db, "Acme", "boss@acme.test"); + let orgs = count(&app.db, "SELECT COUNT(*) FROM orgs", []); + for body in [ + json!({"email": "x@y.test"}), + json!({"name": "", "email": "x@y.test"}), + json!({"name": "N"}), + json!({"name": "N", "email": "nobody"}), + json!({"name": 4, "email": "x@y.test"}), + ] { + let (st, _) = send(&app, "POST", "/operator/orgs", body.clone()); + assert_eq!(st, 400, "{body}"); + } + let (st, _) = send( + &app, + "POST", + "/operator/orgs", + json!({"name": "Dup", "email": "BOSS@acme.test"}), + ); + assert_eq!(st, 409); + assert_eq!(count(&app.db, "SELECT COUNT(*) FROM orgs", []), orgs); + assert!(app.mail.all().is_empty()); + assert!(audit_rows(&app).is_empty()); +} + +#[test] +fn create_with_a_broken_mail_server_keeps_the_org_and_logs_the_failure() { + let app = app(); + *app.mail.fail.lock().unwrap() = true; + let (st, v) = send( + &app, + "POST", + "/operator/orgs", + json!({"name": "Fresh", "email": "new@fresh.test"}), + ); + assert_eq!(st, 200, "{v}"); + assert_eq!(v["mail_sent"], false); + assert!(org_name(&app.db, v["org_id"].as_i64().unwrap()).is_some()); + let rows = audit_rows(&app); + assert_eq!(audit_of(&rows, "org.create").len(), 1); + let failed = audit_of(&rows, "user.reset_mail_failed"); + assert_eq!(failed.len(), 1); + assert_eq!(failed[0]["org_id"], v["org_id"]); + assert!(!failed[0].to_string().contains("fresh.test")); +} + +// --- POST /operator/users/{id}/reset -------------------------------------------------------------- + +#[test] +fn reset_mails_a_token_and_never_returns_it() { + let app = app(); + let (org, user) = customer(&app.db, "Acme", "boss@acme.test"); + let (st, v) = send( + &app, + "POST", + &format!("/operator/users/{user}/reset"), + json!({"org_id": org}), + ); + assert_eq!(st, 200, "{v}"); + assert_eq!(v, json!({"ok": true})); + let mails = app.mail.all(); + assert_eq!(mails.len(), 1); + assert_eq!(mails[0].to, "boss@acme.test"); + assert!(mails[0].body.contains("?reset=sess_")); + assert_eq!( + count( + &app.db, + "SELECT COUNT(*) FROM password_resets WHERE user_id=?", + [user] + ), + 1 + ); + let rows = audit_rows(&app); + let rows = audit_of(&rows, "user.reset"); + assert_eq!(rows.len(), 1); + assert_eq!(rows[0]["org_id"], org); + assert_eq!(rows[0]["target"], format!("user:{user}")); + let text = rows[0].to_string(); + assert!(!text.contains("boss") && !text.contains("sess_"), "{text}"); +} + +#[test] +fn reset_checks_the_org_the_user_and_the_mail_setup() { + let app = app(); + let (org, user) = customer(&app.db, "Acme", "boss@acme.test"); + let (other, _) = customer(&app.db, "Other", "o@other.test"); + let path = format!("/operator/users/{user}/reset"); + // a stale page naming the wrong org + let (st, _) = send(&app, "POST", &path, json!({"org_id": other})); + assert_eq!(st, 409); + let (st, _) = send(&app, "POST", &path, json!({})); + assert_eq!(st, 400); + let (st, _) = send(&app, "POST", &path, json!({"org_id": "2"})); + assert_eq!(st, 400); + let (st, _) = send( + &app, + "POST", + "/operator/users/9999/reset", + json!({"org_id": org}), + ); + assert_eq!(st, 404); + // the seeded legacy user has no e-mail and nothing to mail + let (st, _) = send( + &app, + "POST", + &format!("/operator/users/{}/reset", store::DEFAULT_USER), + json!({"org_id": store::DEFAULT_ORG}), + ); + assert_eq!(st, 404); + assert!(app.mail.all().is_empty()); + assert_eq!( + count(&app.db, "SELECT COUNT(*) FROM password_resets", []), + 0 + ); + assert!(audit_rows(&app).is_empty()); + // no mail setup: 409 + let plain = App::with(hosted_cfg); + let (org, user) = customer(&plain.db, "Acme", "boss@acme.test"); + let (st, v) = send( + &plain, + "POST", + &format!("/operator/users/{user}/reset"), + json!({"org_id": org}), + ); + assert_eq!( + (st, v["error"].as_str()), + (409, Some("mail is not configured")) + ); + assert_eq!( + count(&plain.db, "SELECT COUNT(*) FROM password_resets", []), + 0 + ); +} + +#[test] +fn a_failed_reset_mail_is_a_502_and_a_second_audit_row() { + let app = app(); + let (org, user) = customer(&app.db, "Acme", "boss@acme.test"); + *app.mail.fail.lock().unwrap() = true; + let (st, _) = send( + &app, + "POST", + &format!("/operator/users/{user}/reset"), + json!({"org_id": org}), + ); + assert_eq!(st, 502); + let rows = audit_rows(&app); + assert_eq!(audit_of(&rows, "user.reset").len(), 1); + let failed = audit_of(&rows, "user.reset_mail_failed"); + assert_eq!(failed.len(), 1); + assert_eq!(failed[0]["target"], format!("user:{user}")); + assert_eq!(failed[0]["org_id"], org); + assert!(!failed[0].to_string().contains("smtp") && !failed[0].to_string().contains("acme")); +} + +// --- DELETE /operator/keys/{id} ------------------------------------------------------------------- + +#[test] +fn revoking_a_key_stops_it_and_writes_one_row() { + let app = app(); + let (org, _) = customer(&app.db, "Acme", "boss@acme.test"); + let (other, _) = customer(&app.db, "Other", "o@other.test"); + let (pid, key) = printer_and_key(&app.db, org); + let kid: i64 = app.db.with(|c| { + c.query_row("SELECT id FROM api_keys WHERE org_id=?", [org], |r| { + r.get(0) + }) + .unwrap() + }); + assert_eq!( + app.post( + "/jobs", + Some(&key), + json!({"printer_id": pid, "type": "raw_base64", "content": "QUJD"}) + ) + .0, + 200 + ); + let path = format!("/operator/keys/{kid}"); + // wrong org (a stale page), missing org_id, unknown key + assert_eq!(send(&app, "DELETE", &path, json!({"org_id": other})).0, 409); + assert_eq!(send(&app, "DELETE", &path, json!({})).0, 400); + assert_eq!( + send( + &app, + "DELETE", + "/operator/keys/9999", + json!({"org_id": org}) + ) + .0, + 404 + ); + assert_eq!( + count(&app.db, "SELECT active FROM api_keys WHERE id=?", [kid]), + 1 + ); + let (st, v) = send( + &app, + "DELETE", + &path, + json!({"org_id": org, "reason": "leaked"}), + ); + assert_eq!(st, 200, "{v}"); + assert_eq!( + count(&app.db, "SELECT active FROM api_keys WHERE id=?", [kid]), + 0 + ); + assert_eq!( + app.post( + "/jobs", + Some(&key), + json!({"printer_id": pid, "type": "raw_base64", "content": "QUJD"}) + ) + .0, + 401 + ); + let rows = audit_rows(&app); + let rows = audit_of(&rows, "key.revoke"); + assert_eq!(rows.len(), 1); + assert_eq!(rows[0]["org_id"], org); + assert_eq!(rows[0]["target"], format!("key:{kid}")); + assert_eq!(rows[0]["reason"], "leaked"); + assert!(!rows[0].to_string().contains(&key)); +} + +// --- one transaction with the audit row ----------------------------------------------------------- + +fn break_audit(db: &Db) { + sql( + db, + "CREATE TRIGGER audit_down BEFORE INSERT ON operator_audit \ + BEGIN SELECT RAISE(ABORT, 'audit down'); END", + [], + ); +} + +#[test] +fn a_failing_audit_insert_rolls_every_action_back() { + let app = app(); + let (org, user) = customer(&app.db, "Acme", "boss@acme.test"); + let (pid, key) = printer_and_key(&app.db, org); + let queued = enqueue(&app.db, pid, b"A", |j| j.org_id = Some(org)); + let kid: i64 = app.db.with(|c| { + c.query_row("SELECT id FROM api_keys WHERE org_id=?", [org], |r| { + r.get(0) + }) + .unwrap() + }); + let orgs = count(&app.db, "SELECT COUNT(*) FROM orgs", []); + break_audit(&app.db); + + let (st, _) = send( + &app, + "PUT", + &format!("/operator/orgs/{org}"), + json!({"name": "Renamed", "job_quota": 1}), + ); + assert_eq!(st, 500); + assert_eq!(org_name(&app.db, org).as_deref(), Some("Acme")); + assert_eq!(quota(&app.db, org), Some(100)); + + let (st, _) = send( + &app, + "POST", + &format!("/operator/orgs/{org}/lock"), + json!({"reason": REASON}), + ); + assert_eq!(st, 500); + assert_eq!(count(&app.db, "SELECT COUNT(*) FROM org_locks", []), 0); + assert_eq!(state_of(&app.db, queued).0, "queued"); + + // an existing lock stays when its unlock cannot be written + sql( + &app.db, + "INSERT INTO org_locks(org_id, org_created_at, reason, locked_at) VALUES(?,?,?,?)", + rusqlite::params![org, 1.0, REASON, 2.0], + ); + let (st, _) = send( + &app, + "POST", + &format!("/operator/orgs/{org}/unlock"), + json!({}), + ); + assert_eq!(st, 500); + assert_eq!(count(&app.db, "SELECT COUNT(*) FROM org_locks", []), 1); + sql(&app.db, "DELETE FROM org_locks", []); + + let (st, _) = send( + &app, + "POST", + "/operator/orgs", + json!({"name": "Fresh", "email": "new@fresh.test"}), + ); + assert_eq!(st, 500); + assert_eq!(count(&app.db, "SELECT COUNT(*) FROM orgs", []), orgs); + assert_eq!( + count( + &app.db, + "SELECT COUNT(*) FROM users WHERE email='new@fresh.test'", + [] + ), + 0 + ); + + let (st, _) = send( + &app, + "POST", + &format!("/operator/users/{user}/reset"), + json!({"org_id": org}), + ); + assert_eq!(st, 500); + assert_eq!( + count(&app.db, "SELECT COUNT(*) FROM password_resets", []), + 0 + ); + assert!( + app.mail.all().is_empty(), + "mail went out for a change that was rolled back" + ); + + let (st, _) = send( + &app, + "DELETE", + &format!("/operator/keys/{kid}"), + json!({"org_id": org}), + ); + assert_eq!(st, 500); + assert_eq!( + count(&app.db, "SELECT active FROM api_keys WHERE id=?", [kid]), + 1 + ); + assert_eq!( + app.post( + "/jobs", + Some(&key), + json!({"printer_id": pid, "type": "raw_base64", "content": "QUJD"}) + ) + .0, + 200 + ); + + let (st, _) = send( + &app, + "DELETE", + &format!("/operator/orgs/{org}"), + json!({"reason": REASON, "confirm": "Acme"}), + ); + assert_eq!(st, 500); + assert_eq!(org_name(&app.db, org).as_deref(), Some("Acme")); + assert_eq!( + count(&app.db, "SELECT COUNT(*) FROM jobs WHERE org_id=?", [org]), + 2 + ); + assert_eq!( + count(&app.db, "SELECT COUNT(*) FROM users WHERE id=?", [user]), + 1 + ); +} + +#[test] +fn the_audit_log_holds_no_email_name_or_secret_after_every_action() { + let app = app(); + let (org, user) = customer(&app.db, "Zed Holdings", "zed.boss@zedholdings.test"); + let (pid, key) = printer_and_key(&app.db, org); + enqueue(&app.db, pid, b"A", |j| j.org_id = Some(org)); + let kid: i64 = app.db.with(|c| { + c.query_row("SELECT id FROM api_keys WHERE org_id=?", [org], |r| { + r.get(0) + }) + .unwrap() + }); + send( + &app, + "PUT", + &format!("/operator/orgs/{org}"), + json!({"name": "Zed Renamed", "plan": "pro", "reason": REASON}), + ); + send( + &app, + "POST", + &format!("/operator/orgs/{org}/lock"), + json!({"reason": REASON}), + ); + send( + &app, + "POST", + &format!("/operator/orgs/{org}/unlock"), + json!({}), + ); + send( + &app, + "POST", + &format!("/operator/users/{user}/reset"), + json!({"org_id": org}), + ); + send( + &app, + "DELETE", + &format!("/operator/keys/{kid}"), + json!({"org_id": org}), + ); + let (_, c) = { + let r = op(&app, "POST", "/operator/orgs") + .json(&json!({"name": "Yolo Corp", "email": "yolo@yolocorp.test"})) + .send(); + (r.status, r.json()) + }; + send( + &app, + "DELETE", + &format!("/operator/orgs/{}", c["org_id"]), + json!({"reason": REASON, "confirm": "Yolo Corp"}), + ); + let all = serde_json::to_string(&audit_rows(&app)).unwrap(); + for banned in [ + "Zed", "zed", "Yolo", "yolo", "holdings", "sess_", &key, "PWHASH", "@", + ] { + assert!(!all.contains(banned), "{banned} in {all}"); + } + let actions: Vec = audit_rows(&app) + .iter() + .map(|r| r["action"].as_str().unwrap().to_string()) + .collect(); + for a in [ + "org.update", + "org.lock", + "org.unlock", + "user.reset", + "key.revoke", + "org.create", + "org.delete", + ] { + assert!( + actions.iter().any(|x| x == a), + "{a} missing from {actions:?}" + ); + } +} diff --git a/docs/api.md b/docs/api.md index cbe9411..7b0b11c 100644 --- a/docs/api.md +++ b/docs/api.md @@ -366,6 +366,8 @@ curl -s -X PUT localhost:3460/orgs/2 -H 'Authorization: Bearer ' - A submit past the cap answers **`402`** and prints nothing. The guard sits in the enqueue path, so `POST /jobs`, `POST /orders`, the Shopify webhook and the PrintNode-compatible `POST /printjobs` (`{"code": "QuotaExceeded"}`) are all covered by it. +- An org the operator has [locked](operator.md#lock-and-unlock) answers **`403` `org locked`** on + all of those submit paths, whatever its quota. - An **idempotent resubmit spends nothing** — it returns the original job, it does not create one. - Orgs created through [self-signup](#self-signup) start with the operator's `PRINTAPI_SIGNUP_QUOTA` (none if unset); orgs root creates start unlimited. diff --git a/docs/operator.md b/docs/operator.md index e448de9..21fbb6c 100644 --- a/docs/operator.md +++ b/docs/operator.md @@ -6,8 +6,9 @@ as numbers, an audit log) and nothing in it is specific to one business. **It is `PRINTAPI_OPERATOR_TOKEN` is set**: with the token unset, every path under `/operator/` answers `404`, as if the API did not exist. -This page covers the gate, hosted mode, the audit log and the read endpoints available so far -(overview, orgs and their jobs). +This page covers the gate, hosted mode, the audit log, the read endpoints (overview, orgs and their +jobs) and the write endpoints (change, lock, delete and create an org, send a reset mail, revoke a +key). ## The gate @@ -170,5 +171,86 @@ Query: `limit` (default 50, at most 200), `before_id`. Newest first by id. Each on the last one. The reads add indexes (`jobs(org_id)`, `jobs(org_id, state)` and three small ones) to an existing -database at startup. They are additive and the Python server of v2.x ignores them. The `org_locks` -table that holds the lock row is created empty; locking itself comes with the write endpoints. +database at startup. They are additive and the Python server of v2.x ignores them. + +## Writes + +Every write is **one store function and one transaction with its audit row**: the change and the +row are committed together or not at all. If the audit row cannot be written, the change is rolled +back and the answer is `500`. A mail and the WAL truncate that belong to an action run **after** the +commit. Bodies are JSON; the optional `reason` is a string of at most 500 characters and lands in +the audit log, so keep customer data out of it. An org or id that does not exist answers `404`; a +body that is not a JSON object, or a field that fails validation, answers `400` and changes nothing. + +| Call | Audit action | +|---|---| +| `PUT /operator/orgs/{id}` | `org.update` | +| `POST /operator/orgs/{id}/lock`, `.../unlock` | `org.lock`, `org.unlock` | +| `DELETE /operator/orgs/{id}` | `org.delete` | +| `POST /operator/orgs` | `org.create` | +| `POST /operator/users/{id}/reset` | `user.reset` (`user.reset_mail_failed` when the mail did not go out) | +| `DELETE /operator/keys/{id}` | `key.revoke` | + +The audit rows hold ids and numbers: `org.update` says which fields changed (`name: true`, never the +name), `org.lock` how many queued jobs it cancelled, `org.create` the quota the org started with. +No e-mail address, org name or title is ever written. + +### `PUT /operator/orgs/{id}` + +`{name?, job_quota?, plan?, reason?}`, at least one of the three fields. Everything is validated +first and applied in one transaction. `name` is a non-empty string of at most 200 characters; +`job_quota` a non-negative integer or `null` (unlimited); `plan` an id of the plan catalogue +([billing](billing.md)), which also sets the quota the plan grants. An explicit `job_quota` in the +same body wins over the plan's. Answer: `{"ok": true}`. + +### Lock and unlock + +`POST /operator/orgs/{id}/lock` with `{reason}` of at least 8 characters inserts a row into the +table `org_locks` (`org_id`, `org_created_at`, `reason`, `locked_at`) and cancels the org's queued +jobs (`error: "org locked"`; a job an agent already claimed runs on). Answer: +`{"ok": true, "cancelled_jobs": 3}`; `409` if the org is already locked. + +A lock is a **pure flag**: quota and plan stay as they are, so billing and quota writes need no +change. While it is set, every way a job gets in answers **`403` `org locked`**: `POST /jobs`, +`POST /orders`, the Shopify webhook and the PrintNode-compatible `POST /printjobs`. The check sits +next to the quota check in the enqueue path and again before any payload is downloaded, so a locked +org causes no outbound request, and an idempotent resubmit does not get an old job back either. +Logins, the dashboard and agents keep working, so the customer can see what is going on. + +`POST /operator/orgs/{id}/unlock` (`{reason?}`) deletes the row; `409` if the org is not locked. +`GET /operator/orgs` and the org detail show the lock (`locked`, `status: "locked"`, `lock`). + +> **Rolling back to an older version drops the lock.** Versions before this one (and the Python +> server of v2.x) do not read `org_locks`: a locked org can submit again, and the table is kept +> untouched. Unlock first, or accept that. Deleting an org there also leaves its lock row behind, so +> a later org that reuses the id would still read as locked on a newer version. + +### `DELETE /operator/orgs/{id}` + +`{reason, confirm}`: `confirm` must equal the org's **current name** exactly, otherwise `400`. The +default org is never removed (`400`). The org's jobs, printers, agents, keys, accounts, label +templates, terms history and its `org_locks` row go with it; the audit rows stay. The WAL is +truncated after the commit, so removed payloads do not linger in the `-wal` file. + +### `POST /operator/orgs` + +`{name, email, reason?}` creates the org with the signup quota (`PRINTAPI_SIGNUP_QUOTA`, as a +self-signup would get) and its first user. The user's password hash is that of 32 random bytes, +never `NULL`, so a login attempt reveals nothing; the **reset mail is the invitation**, sent after +the commit. Answer: `{"ok": true, "org_id", "user_id", "mail_sent"}`. Without mail (`SMTP_HOST`) and +`PUBLIC_URL` the answer is `409` `mail is not configured` and nothing is created; a taken address is +`409` too. If the mail server fails after the commit, the org stays, `mail_sent` is `false` and a +`user.reset_mail_failed` row is written: use the reset below to send it again. + +### `POST /operator/users/{id}/reset` + +`{org_id, reason?}` sends a password-reset mail to the user and never returns the token. `org_id` +must be the user's org (`409` otherwise), so a stale page cannot reach a user that reuses an id. `409` +`mail is not configured` without mail and `PUBLIC_URL`; `502` if the mail did not go out (the row +`user.reset_mail_failed` says so). A user without an e-mail address (the seeded legacy one) is `404`. + +### `DELETE /operator/keys/{id}` + +`{org_id, reason?}` revokes an API key (`409` if the key belongs to another org). Agents enrolled +with it end their long-poll with `401`. Removing a single user is not offered here: customers remove +their own accounts, and root still can. diff --git a/docs/server.md b/docs/server.md index 1478862..c3e34e7 100644 --- a/docs/server.md +++ b/docs/server.md @@ -50,7 +50,7 @@ Environment variables: | `PRINTAPI_PRIVATE_URLS` | `deny` with open signup or an [operator token](operator.md#hosted-mode), else `allow` | `deny`: payload URLs (`*_uri`, `*_uri_post`), job `callback_url`s and org `event_url`s may only reach public addresses — no loopback, LAN, link-local/cloud-metadata or other private ranges, checked after DNS on every redirect hop. `allow`: anywhere (a self-hosted box fetching PDFs from an internal service). Set `deny` whenever people you do not trust get keys | | `PRINTAPI_TRUSTED_PROXIES` | *(unset: nobody)* | Comma-separated IPs or CIDRs (IPv4 and IPv6, e.g. `127.0.0.1,::1` or the one pinned proxy address `172.30.0.2` of the Compose example; list nothing wider) of the reverse proxies in front of printpapi. Only a request whose socket peer is listed has its `X-Forwarded-For` read: the rightmost entry that is not itself listed is the client, which the signup throttle (IPv6 per /64) and the `LOG_REQUESTS` line then use. Unset, the socket peer is the client, so behind a proxy every signup shares one throttle slot. An invalid entry stops the server at startup. See [Behind a reverse proxy](#behind-a-reverse-proxy) | | `PRINTAPI_OPEN_ENROLLMENT` | *(off)* | `1`: any Bearer value enrolls a new agent into the default org (the v2 rule). Off: a new agent needs an issued key or the root token | -| `PRINTAPI_OPERATOR_TOKEN` | *(unset: no operator API)* | Set: the [operator API](operator.md) under `/operator/` is on, for the console of a hosted deployment, and so is hosted mode (private URLs denied, 4 downloads per org, unless you set them). At least 32 characters, not starting with `sess_`, different from `PRINTAPI_TOKEN`; anything else stops the server at startup. Unset, every `/operator/` path answers `404` | +| `PRINTAPI_OPERATOR_TOKEN` | *(unset: no operator API)* | Set: the [operator API](operator.md) under `/operator/` is on (reads and writes: org changes, locks, deletes, invitations, reset mails, key revokes, each in the audit log; invitations and reset mails need `SMTP_HOST` and `PUBLIC_URL`), for the console of a hosted deployment, and so is hosted mode (private URLs denied, 4 downloads per org, unless you set them). At least 32 characters, not starting with `sess_`, different from `PRINTAPI_TOKEN`; anything else stops the server at startup. Unset, every `/operator/` path answers `404` | | `PRINTAPI_OPERATOR_FROM` | *(required with the operator token)* | Comma-separated IPs or CIDRs (the `PRINTAPI_TRUSTED_PROXIES` syntax) the operator token is accepted from, matched against the **socket peer**, never `X-Forwarded-For`. From any other address the token is an unknown credential. Missing or invalid with the token set stops the server at startup | ```bash From 1fc61cba225990f99e9da165615b06bd1f916421 Mon Sep 17 00:00:00 2001 From: Lukas Date: Sat, 14 Nov 2026 02:12:28 +0100 Subject: [PATCH 5/5] fix(server): operator writes check the org generation, locks only with the token, no requeue for locked orgs Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01TEvvb3zrZ3bLSGJbCBaEYX --- crates/server/src/main.rs | 7 + crates/server/src/server.rs | 20 +- crates/server/src/server/operator.rs | 50 +++- crates/server/src/store.rs | 111 +++++++- crates/server/tests/binary.rs | 41 +++ crates/server/tests/http_operator.rs | 8 +- crates/server/tests/http_operator_writes.rs | 285 +++++++++++++++++++- crates/server/tests/store_compat.rs | 5 +- docs/operator.md | 32 ++- 9 files changed, 517 insertions(+), 42 deletions(-) diff --git a/crates/server/src/main.rs b/crates/server/src/main.rs index 875cb93..5fe487a 100644 --- a/crates/server/src/main.rs +++ b/crates/server/src/main.rs @@ -287,6 +287,7 @@ async fn shutdown_signal() { fn run() -> Result<(), String> { let (cfg, db_path, port) = config()?; let destinations = cfg.destinations; + let hosted_locks_enforced = cfg.operator_token.is_some(); for line in startup_warnings(&cfg) { eprintln!("{line}"); } @@ -294,6 +295,12 @@ fn run() -> Result<(), String> { eprintln!("operator API on (hosted mode: private URLs denied unless allowed explicitly)"); } let db = Db::open(&db_path).map_err(|e| format!("cannot open database {db_path:?}: {e}"))?; + if !hosted_locks_enforced + && let Ok(n) = db.with(printpapi_server::store::count_org_locks) + && n > 0 + { + eprintln!("{n} org locks are not enforced: PRINTAPI_OPERATOR_TOKEN is unset"); + } let state = Arc::new(AppState::new( cfg, db, diff --git a/crates/server/src/server.rs b/crates/server/src/server.rs index 202677d..3aad8c7 100644 --- a/crates/server/src/server.rs +++ b/crates/server/src/server.rs @@ -1286,7 +1286,9 @@ impl Ctx<'_> { }; // One closure, so a retry cannot see "no job yet" and then a quota the original used up. let checked = self.db(|c| { - store::check_not_locked(c, printer.org_id)?; + if self.cfg().operator_token.is_some() { + store::check_not_locked(c, printer.org_id)?; + } if let Some(key) = key && let Some(e) = store::find_job_by_key(c, printer.org_id, key)? { @@ -1403,7 +1405,8 @@ impl Ctx<'_> { } fn enqueue(&self, job: &store::NewJob<'_>) -> Result { - match self.db(|c| store::enqueue_job(c, job)) { + let locks = self.cfg().operator_token.is_some(); + match self.db(|c| store::enqueue_job_with(c, job, locks)) { Ok(e) => { if e.created { self.s.waker.wake(e.agent_id); @@ -2747,10 +2750,15 @@ pub fn retention_pass(state: &AppState, now: f64) -> Option { pub fn reaper_pass(state: &AppState, timeout_s: f64, max_retries: i64) { let run = || -> store::Result<()> { state.db.with(|c| store::expire_jobs(c, None))?; - if state - .db - .with(|c| store::requeue_stale(c, timeout_s, max_retries, None))? - > 0 + if state.db.with(|c| { + store::requeue_stale( + c, + timeout_s, + max_retries, + None, + state.cfg.operator_token.is_some(), + ) + })? > 0 { state.waker.wake_all(); } diff --git a/crates/server/src/server/operator.rs b/crates/server/src/server/operator.rs index 79ace5c..c17015b 100644 --- a/crates/server/src/server/operator.rs +++ b/crates/server/src/server/operator.rs @@ -81,6 +81,16 @@ fn name_of(v: Option<&Value>, what: &str) -> Gate { } /// The `org_id` a write names to prove its page is not stale. +/// The `org_created_at` the console's page showed (the org's `created_at` of the read endpoints). +/// Missing or not a number: `None`, which matches no org, so the write is refused as stale. +fn seen_of(body: &Obj) -> Option { + body.get("org_created_at").and_then(Value::as_f64) +} + +fn org_changed() -> Resp { + jerr(409, "the org changed, reload") +} + fn org_id_of(body: &Obj) -> Gate { body.get("org_id") .and_then(Value::as_i64) @@ -281,22 +291,26 @@ impl Ctx<'_> { return Ok(jerr(400, "nothing to update")); } let detail = Value::Object(detail); - let out = - self.db(|c| store::operator_update_org(c, id, &update, reason.as_deref(), &detail))?; + let seen = seen_of(&body); + let out = self + .db(|c| store::operator_update_org(c, id, seen, &update, reason.as_deref(), &detail))?; Ok(match out { store::Outcome::Done(()) => ok_true(), - _ => not_found(), + store::Outcome::Refused(_) => org_changed(), + store::Outcome::NotFound => not_found(), }) } fn operator_org_lock(&self, id: i64) -> R { let body = gate!(self.read_obj()); let reason = gate!(reason_of(&body, LOCK_REASON_MIN)).unwrap_or_default(); + let seen = seen_of(&body); Ok( - match self.db(|c| store::operator_lock_org(c, id, &reason))? { + match self.db(|c| store::operator_lock_org(c, id, seen, &reason))? { store::Outcome::Done(n) => { Resp::json(200, &json!({ "ok": true, "cancelled_jobs": n })) } + store::Outcome::Refused(store::Refusal::OrgChanged) => org_changed(), store::Outcome::Refused(_) => jerr(409, "org is already locked"), store::Outcome::NotFound => not_found(), }, @@ -306,9 +320,11 @@ impl Ctx<'_> { fn operator_org_unlock(&self, id: i64) -> R { let body = gate!(self.read_obj()); let reason = gate!(reason_of(&body, 0)); + let seen = seen_of(&body); Ok( - match self.db(|c| store::operator_unlock_org(c, id, reason.as_deref()))? { + match self.db(|c| store::operator_unlock_org(c, id, seen, reason.as_deref()))? { store::Outcome::Done(()) => ok_true(), + store::Outcome::Refused(store::Refusal::OrgChanged) => org_changed(), store::Outcome::Refused(_) => jerr(409, "org is not locked"), store::Outcome::NotFound => not_found(), }, @@ -321,7 +337,8 @@ impl Ctx<'_> { let Some(Value::String(confirm)) = body.get("confirm") else { return Ok(jerr(400, "confirm must be the org name")); }; - let out = self.db(|c| store::operator_delete_org(c, id, confirm, &reason))?; + let seen = seen_of(&body); + let out = self.db(|c| store::operator_delete_org(c, id, seen, confirm, &reason))?; Ok(match out { store::Outcome::Done(()) => { // secure_delete zeroed the pages; this clears the WAL frames too. A reader can @@ -332,6 +349,7 @@ impl Ctx<'_> { store::Outcome::Refused(store::Refusal::DefaultOrg) => { jerr(400, "the default org cannot be removed") } + store::Outcome::Refused(store::Refusal::OrgChanged) => org_changed(), store::Outcome::Refused(_) => jerr(400, "confirm must be the org name"), store::Outcome::NotFound => not_found(), }) @@ -379,8 +397,12 @@ impl Ctx<'_> { "You have been invited to printpapi. Choose a password with the link below.", &tok, ); + let created = self + .db(|c| store::org_created_at(c, new.org_id)) + .unwrap_or(None); let row = store::AuditRow { org_id: Some(new.org_id), + org_created_at: created, target: Some(&format!("user:{}", new.user_id)), ..Default::default() }; @@ -400,10 +422,13 @@ impl Ctx<'_> { } let tok = auth::new_session_token(); let ttl = self.cfg().reset_ttl_s; - let out = self - .db(|c| store::operator_reset_user(c, user_id, org_id, &tok, ttl, reason.as_deref()))?; + let seen = seen_of(&body); + let out = self.db(|c| { + store::operator_reset_user(c, user_id, org_id, seen, &tok, ttl, reason.as_deref()) + })?; let email = match out { store::Outcome::Done(e) => e, + store::Outcome::Refused(store::Refusal::OrgChanged) => return Ok(org_changed()), store::Outcome::Refused(_) => return Ok(jerr(409, "user belongs to another org")), store::Outcome::NotFound => return Ok(not_found()), }; @@ -411,8 +436,12 @@ impl Ctx<'_> { "An operator started a password reset for your printpapi account.", &tok, ); + let created = self + .db(|c| store::org_created_at(c, org_id)) + .unwrap_or(None); let row = store::AuditRow { org_id: Some(org_id), + org_created_at: created, target: Some(&format!("user:{user_id}")), ..Default::default() }; @@ -427,13 +456,16 @@ impl Ctx<'_> { let body = gate!(self.read_obj()); let org_id = gate!(org_id_of(&body)); let reason = gate!(reason_of(&body, 0)); - let out = self.db(|c| store::operator_revoke_key(c, key_id, org_id, reason.as_deref()))?; + let seen = seen_of(&body); + let out = + self.db(|c| store::operator_revoke_key(c, key_id, org_id, seen, reason.as_deref()))?; Ok(match out { store::Outcome::Done(()) => { // a long-poll of an agent enrolled with this key re-checks it and ends with 401 self.s.waker.wake_all(); ok_true() } + store::Outcome::Refused(store::Refusal::OrgChanged) => org_changed(), store::Outcome::Refused(_) => jerr(409, "key belongs to another org"), store::Outcome::NotFound => not_found(), }) diff --git a/crates/server/src/store.rs b/crates/server/src/store.rs index f650053..6037f11 100644 --- a/crates/server/src/store.rs +++ b/crates/server/src/store.rs @@ -1444,11 +1444,28 @@ pub fn get_printer( .optional()?) } +/// How many orgs are locked right now (current generation only). +pub fn count_org_locks(conn: &Connection) -> Result { + Ok(conn.query_row( + "SELECT COUNT(*) FROM org_locks l JOIN orgs o \ + ON o.id = l.org_id AND o.created_at = l.org_created_at", + [], + |r| r.get(0), + )?) +} + /// `Locked` while the operator has locked `org_id`. A pure flag: quota and plan are not looked at. /// Checked next to `check_quota` wherever a job may enter, and before any payload is fetched. +/// +/// A lock row counts only while its `org_created_at` is the org's: a row left by an earlier org +/// of the same (reused) id locks nothing. Callers enforce locks only while the operator token is +/// configured (`Config::operator_token`): without it nothing could show or lift one. pub fn check_not_locked(conn: &Connection, org_id: i64) -> Result<()> { let locked = conn - .prepare_cached("SELECT 1 FROM org_locks WHERE org_id=?")? + .prepare_cached( + "SELECT 1 FROM org_locks l JOIN orgs o \ + ON o.id = l.org_id AND o.created_at = l.org_created_at WHERE l.org_id=?", + )? .query_row([org_id], |_| Ok(())) .optional()? .is_some(); @@ -1494,7 +1511,17 @@ pub fn find_job_by_key(conn: &Connection, org_id: i64, key: &str) -> Result) -> Result { + enqueue_job_with(conn, job, true) +} + +/// `enforce_locks` is false while the operator token is unset (see `check_not_locked`). +pub fn enqueue_job_with( + conn: &Connection, + job: &NewJob<'_>, + enforce_locks: bool, +) -> Result { let now = crate::now(); let unknown = || { StoreError::UnknownPrinter(format!( @@ -1517,7 +1544,9 @@ pub fn enqueue_job(conn: &Connection, job: &NewJob<'_>) -> Result { return Err(unknown()); }; // before the idempotency lookup: a locked org gets no job, not even an old one back - check_not_locked(&tx, org_id)?; + if enforce_locks { + check_not_locked(&tx, org_id)?; + } if let Some(key) = &job.idempotency_key { // A retried submit returns the original job — the same key never prints twice in an org. // The lookup is safe under the write transaction; the UNIQUE index enforces it. @@ -1678,16 +1707,28 @@ pub fn finish_job( Ok(n == 1) } -/// Returns how many jobs went back to `queued`. +/// Returns how many jobs went back to `queued`. With `enforce_locks` a stale job of a locked org +/// is cancelled (`error: "org locked"`) instead: it was claimed before the lock, and a requeue +/// would hand it out again. pub fn requeue_stale( conn: &Connection, timeout_s: f64, max_retries: i64, now: Option, + enforce_locks: bool, ) -> Result { let now = now.unwrap_or_else(crate::now); let cutoff = now - timeout_s; let tx = begin(conn)?; + if enforce_locks { + tx.execute( + "UPDATE jobs SET state='cancelled', error='org locked', finished_at=? \ + WHERE state='claimed' AND claimed_at < ? AND org_id IN \ + (SELECT l.org_id FROM org_locks l JOIN orgs o \ + ON o.id = l.org_id AND o.created_at = l.org_created_at)", + params![now, cutoff], + )?; + } tx.execute( "UPDATE jobs SET state='failed', error='retry limit exceeded', finished_at=? \ WHERE state='claimed' AND claimed_at < ? AND retries >= ?", @@ -2357,13 +2398,16 @@ pub enum Refusal { NotLocked, /// The id belongs to another org than the caller named (a stale page, a reused id). OrgMismatch, + /// The org is not the generation the caller saw (`org_created_at`): deleted and recreated + /// under the same id, or no generation named. + OrgChanged, /// The typed name is not the org's current name. ConfirmMismatch, DefaultOrg, } /// When the org was created: what keeps a reused org id apart in the audit log. -fn org_created_at(tx: &Transaction, org_id: i64) -> Result> { +pub fn org_created_at(tx: &Connection, org_id: i64) -> Result> { Ok(tx .query_row("SELECT created_at FROM orgs WHERE id=?", [org_id], |r| { r.get(0) @@ -2375,6 +2419,7 @@ fn org_created_at(tx: &Transaction, org_id: i64) -> Result> { pub fn operator_update_org( conn: &Connection, org_id: i64, + seen: Option, u: &OrgUpdate, reason: Option<&str>, detail: &Value, @@ -2383,6 +2428,9 @@ pub fn operator_update_org( let Some(created) = org_created_at(&tx, org_id)? else { return Ok(Outcome::NotFound); }; + if seen != Some(created) { + return Ok(Outcome::Refused(Refusal::OrgChanged)); + } update_org_tx(&tx, org_id, u)?; insert_audit( &tx, @@ -2401,12 +2449,25 @@ pub fn operator_update_org( /// `org.lock`: the flag row, and the org's queued jobs cancelled (`error: "org locked"`). Returns /// how many. Claimed jobs run on; quota and plan stay as they are. -pub fn operator_lock_org(conn: &Connection, org_id: i64, reason: &str) -> Result> { +pub fn operator_lock_org( + conn: &Connection, + org_id: i64, + seen: Option, + reason: &str, +) -> Result> { let tx = begin(conn)?; let Some(created) = org_created_at(&tx, org_id)? else { return Ok(Outcome::NotFound); }; + if seen != Some(created) { + return Ok(Outcome::Refused(Refusal::OrgChanged)); + } let now = crate::now(); + // a row of an earlier org of this id locks nothing: make room for the real one + tx.execute( + "DELETE FROM org_locks WHERE org_id=? AND org_created_at<>?", + params![org_id, created], + )?; let inserted = tx.execute( "INSERT OR IGNORE INTO org_locks(org_id, org_created_at, reason, locked_at) VALUES(?,?,?,?)", params![org_id, created, reason, now], @@ -2438,13 +2499,21 @@ pub fn operator_lock_org(conn: &Connection, org_id: i64, reason: &str) -> Result pub fn operator_unlock_org( conn: &Connection, org_id: i64, + seen: Option, reason: Option<&str>, ) -> Result> { let tx = begin(conn)?; let Some(created) = org_created_at(&tx, org_id)? else { return Ok(Outcome::NotFound); }; - if tx.execute("DELETE FROM org_locks WHERE org_id=?", [org_id])? == 0 { + if seen != Some(created) { + return Ok(Outcome::Refused(Refusal::OrgChanged)); + } + if tx.execute( + "DELETE FROM org_locks WHERE org_id=? AND org_created_at=?", + params![org_id, created], + )? == 0 + { return Ok(Outcome::Refused(Refusal::NotLocked)); } insert_audit( @@ -2466,6 +2535,7 @@ pub fn operator_unlock_org( pub fn operator_delete_org( conn: &Connection, org_id: i64, + seen: Option, confirm: &str, reason: &str, ) -> Result> { @@ -2483,6 +2553,9 @@ pub fn operator_delete_org( let Some((name, created)) = found else { return Ok(Outcome::NotFound); }; + if seen != Some(created) { + return Ok(Outcome::Refused(Refusal::OrgChanged)); + } if name != confirm { return Ok(Outcome::Refused(Refusal::ConfirmMismatch)); } @@ -2540,6 +2613,7 @@ pub fn operator_reset_user( conn: &Connection, user_id: i64, org_id: i64, + seen: Option, token: &str, ttl_s: f64, reason: Option<&str>, @@ -2558,13 +2632,17 @@ pub fn operator_reset_user( if owner != org_id { return Ok(Outcome::Refused(Refusal::OrgMismatch)); } + let created = org_created_at(&tx, org_id)?; + if created.is_none() || seen != created { + return Ok(Outcome::Refused(Refusal::OrgChanged)); + } create_password_reset_tx(&tx, user_id, token, ttl_s, None)?; insert_audit( &tx, &AuditRow { action: "user.reset", org_id: Some(org_id), - org_created_at: org_created_at(&tx, org_id)?, + org_created_at: created, target: Some(&format!("user:{user_id}")), reason, ..Default::default() @@ -2587,6 +2665,7 @@ pub fn operator_revoke_key( conn: &Connection, key_id: i64, org_id: i64, + seen: Option, reason: Option<&str>, ) -> Result> { let tx = begin(conn)?; @@ -2601,13 +2680,17 @@ pub fn operator_revoke_key( if owner != org_id { return Ok(Outcome::Refused(Refusal::OrgMismatch)); } + let created = org_created_at(&tx, org_id)?; + if created.is_none() || seen != created { + return Ok(Outcome::Refused(Refusal::OrgChanged)); + } revoke_api_key_tx(&tx, key_id, Some(org_id))?; insert_audit( &tx, &AuditRow { action: "key.revoke", org_id: Some(org_id), - org_created_at: org_created_at(&tx, org_id)?, + org_created_at: created, target: Some(&format!("key:{key_id}")), reason, ..Default::default() @@ -2674,7 +2757,8 @@ SELECT * FROM ( (SELECT COUNT(*) FROM agents a WHERE a.org_id = o.id) AS agents_total, (SELECT MAX(a.last_seen_at) FROM agents a WHERE a.org_id = o.id) AS newest_agent_seen_at, (SELECT COUNT(*) FROM printers p WHERE p.org_id = o.id) AS printers, - EXISTS(SELECT 1 FROM org_locks l WHERE l.org_id = o.id) AS locked, + EXISTS(SELECT 1 FROM org_locks l WHERE l.org_id = o.id + AND l.org_created_at = o.created_at) AS locked, (SELECT u.email FROM users u WHERE u.org_id = o.id AND u.email IS NOT NULL ORDER BY u.id LIMIT 1) AS first_user_email, (SELECT t.version FROM terms_acceptances t WHERE t.org_id = o.id @@ -2880,7 +2964,8 @@ pub fn operator_org_parts(conn: &Connection, org_id: i64) -> Result { .collect::>()?; let lock = conn .query_row( - "SELECT reason, locked_at FROM org_locks WHERE org_id = ?", + "SELECT l.reason, l.locked_at FROM org_locks l JOIN orgs o \ + ON o.id = l.org_id AND o.created_at = l.org_created_at WHERE l.org_id = ?", [org_id], |r| { Ok(OperatorLock { @@ -3381,9 +3466,9 @@ mod tests { let jid = enq(&conn, pid, b"x"); claim_job(&conn, aid, None).unwrap(); let base = crate::now(); - assert_eq!(requeue_stale(&conn, 60.0, 1, Some(base)).unwrap(), 0); // not stale yet + assert_eq!(requeue_stale(&conn, 60.0, 1, Some(base), false).unwrap(), 0); // not stale yet assert_eq!( - requeue_stale(&conn, 60.0, 1, Some(base + 120.0)).unwrap(), + requeue_stale(&conn, 60.0, 1, Some(base + 120.0), false).unwrap(), 1 ); // under limit assert_eq!(state_of(&conn, jid), "queued"); @@ -3393,7 +3478,7 @@ mod tests { ); claim_job(&conn, aid, None).unwrap(); // claim again, go stale again -> over the limit assert_eq!( - requeue_stale(&conn, 60.0, 1, Some(base + 300.0)).unwrap(), + requeue_stale(&conn, 60.0, 1, Some(base + 300.0), false).unwrap(), 0 ); assert_eq!(state_of(&conn, jid), "failed"); diff --git a/crates/server/tests/binary.rs b/crates/server/tests/binary.rs index 71f8bd2..bda0ba6 100644 --- a/crates/server/tests/binary.rs +++ b/crates/server/tests/binary.rs @@ -273,3 +273,44 @@ fn open_signup_without_terms_warns_on_stderr() { assert!(!err.contains("PRINTAPI_TERMS_VERSION"), "{err:?}"); assert!(!stderr_at_startup(&[]).contains("PRINTAPI_TERMS_VERSION")); } + +#[test] +fn locks_without_the_operator_token_are_reported_at_startup() { + use printpapi_server::store::{self, Db}; + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("locks.db"); + { + let db = Db::open(path.to_str().unwrap()).unwrap(); + db.with(|c| { + let s = store::signup(c, "Acme", "boss@acme.test", "PWHASH", None, None).unwrap(); + let created: f64 = c + .query_row("SELECT created_at FROM orgs WHERE id=?", [s.org_id], |r| { + r.get(0) + }) + .unwrap(); + c.execute( + "INSERT INTO org_locks(org_id, org_created_at, reason, locked_at) VALUES(?,?,?,?)", + rusqlite::params![s.org_id, created, "support ticket", 1.0], + ) + .unwrap(); + }); + } + let db = path.to_str().unwrap(); + let err = stderr_at_startup(&[("PRINT_DB", db)]); + assert!( + err.contains("1 org locks are not enforced: PRINTAPI_OPERATOR_TOKEN is unset"), + "{err:?}" + ); + // with the token the locks hold: no line + let err = stderr_at_startup(&[ + ("PRINT_DB", db), + ( + "PRINTAPI_OPERATOR_TOKEN", + "operator-token-0123456789abcdef-xyz", + ), + ("PRINTAPI_OPERATOR_FROM", "10.9.0.2"), + ]); + assert!(!err.contains("not enforced"), "{err:?}"); + // and a database without locks says nothing + assert!(!stderr_at_startup(&[]).contains("not enforced")); +} diff --git a/crates/server/tests/http_operator.rs b/crates/server/tests/http_operator.rs index 87aa411..0341e92 100644 --- a/crates/server/tests/http_operator.rs +++ b/crates/server/tests/http_operator.rs @@ -750,8 +750,8 @@ fn org_status_is_locked_new_idle_or_active_and_filters() { job_at(&app, locked, 60.0, |_| {}); sql( &app.db, - "INSERT INTO org_locks(org_id, org_created_at, reason, locked_at) VALUES(?,?,?,?)", - rusqlite::params![locked, now() - DAY, "unpaid invoice", now()], + "INSERT INTO org_locks(org_id, org_created_at, reason, locked_at) \n SELECT id, created_at, ?, ? FROM orgs WHERE id=?", + rusqlite::params!["unpaid invoice", now(), locked], ); let (st, v) = app.get_op("/operator/orgs"); assert_eq!(st, 200, "{v}"); @@ -907,8 +907,8 @@ fn org_detail_has_usage_users_agents_printers_keys_terms_and_lock() { // a lock shows up with its reason sql( &app.db, - "INSERT INTO org_locks(org_id, org_created_at, reason, locked_at) VALUES(?,?,?,?)", - rusqlite::params![acme, 1.0, "unpaid invoice", 1_700_000_500.0], + "INSERT INTO org_locks(org_id, org_created_at, reason, locked_at) \n SELECT id, created_at, ?, ? FROM orgs WHERE id=?", + rusqlite::params!["unpaid invoice", 1_700_000_500.0, acme], ); let (_, v) = app.get_op(&format!("/operator/orgs/{acme}")); assert_eq!( diff --git a/crates/server/tests/http_operator_writes.rs b/crates/server/tests/http_operator_writes.rs index c95b218..3f42a44 100644 --- a/crates/server/tests/http_operator_writes.rs +++ b/crates/server/tests/http_operator_writes.rs @@ -47,11 +47,38 @@ fn op<'a>(app: &'a App, method: &str, target: &str) -> Call<'a> { app.call(method, target).bearer(OP).socket(CONSOLE) } -fn send(app: &App, method: &str, target: &str, body: Value) -> (u16, Value) { +/// The write as the console sends it: the body carries `org_created_at`, the generation of the +/// org the page showed (looked up here, unless the test names one itself). +fn send(app: &App, method: &str, target: &str, mut body: Value) -> (u16, Value) { + let org = match target.strip_prefix("/operator/orgs/") { + Some(rest) => rest.split('/').next().and_then(|s| s.parse::().ok()), + None => body["org_id"].as_i64(), + }; + if let Some(org) = org + && let Some(obj) = body.as_object_mut() + && !obj.contains_key("org_created_at") + && let Some(created) = created_of(&app.db, org) + { + obj.insert("org_created_at".into(), json!(created)); + } + send_bare(app, method, target, body) +} + +/// The write exactly as given. +fn send_bare(app: &App, method: &str, target: &str, body: Value) -> (u16, Value) { let r = op(app, method, target).json(&body).send(); (r.status, r.json()) } +fn created_of(db: &Db, org: i64) -> Option { + db.with(|c| { + c.query_row("SELECT created_at FROM orgs WHERE id=?", [org], |r| { + r.get(0) + }) + .ok() + }) +} + fn sql(db: &Db, q: &str, p: impl rusqlite::Params) { db.with(|c| c.execute(q, p).unwrap()); } @@ -1125,8 +1152,8 @@ fn a_failing_audit_insert_rolls_every_action_back() { // an existing lock stays when its unlock cannot be written sql( &app.db, - "INSERT INTO org_locks(org_id, org_created_at, reason, locked_at) VALUES(?,?,?,?)", - rusqlite::params![org, 1.0, REASON, 2.0], + "INSERT INTO org_locks(org_id, org_created_at, reason, locked_at) SELECT id, created_at, ?, ? FROM orgs WHERE id=?", + rusqlite::params![REASON, 2.0, org], ); let (st, _) = send( &app, @@ -1289,3 +1316,255 @@ fn the_audit_log_holds_no_email_name_or_secret_after_every_action() { ); } } + +// --- the org generation: a reused id is not the org the page showed ----------------------------- + +/// An org is deleted and a new customer signs up under the same id. Returns (org id, user id, key +/// id of the new org, the old org's created_at). +fn reborn(app: &App) -> (i64, i64, i64, f64) { + let (org, _) = customer(&app.db, "Acme", "boss@acme.test"); + let old = created_of(&app.db, org).unwrap(); + assert!(app.db.with(|c| store::delete_org(c, org)).unwrap()); + let (again, user) = customer(&app.db, "Newcomer", "new@newcomer.test"); + assert_eq!(again, org, "SQLite reuses the id of the newest row"); + // the clock may not have ticked: make the generations differ for certain + sql( + &app.db, + "UPDATE orgs SET created_at=? WHERE id=?", + rusqlite::params![old + 10.0, org], + ); + add_key(&app.db, "k", "newcomer-key", org); + let kid = count(&app.db, "SELECT id FROM api_keys WHERE org_id=?", [org]); + (org, user, kid, old) +} + +#[test] +fn every_write_with_an_old_org_generation_is_409_and_changes_nothing() { + let app = app(); + let (org, user, kid, old) = reborn(&app); + let calls = [ + ( + "PUT", + format!("/operator/orgs/{org}"), + json!({"name": "Renamed"}), + ), + ( + "POST", + format!("/operator/orgs/{org}/lock"), + json!({"reason": REASON}), + ), + ("POST", format!("/operator/orgs/{org}/unlock"), json!({})), + ( + "DELETE", + format!("/operator/orgs/{org}"), + json!({"reason": REASON, "confirm": "Newcomer"}), + ), + ( + "POST", + format!("/operator/users/{user}/reset"), + json!({"org_id": org}), + ), + ( + "DELETE", + format!("/operator/keys/{kid}"), + json!({"org_id": org}), + ), + ]; + let created = created_of(&app.db, org).unwrap(); + let lock_row = |app: &App| { + sql( + &app.db, + "INSERT INTO org_locks(org_id, org_created_at, reason, locked_at) VALUES(?,?,?,?)", + rusqlite::params![org, created, REASON, 2.0], + ) + }; + for stale in [Some(old), None] { + for (m, p, body) in &calls { + let mut body = body.clone(); + if let Some(old) = stale { + body["org_created_at"] = json!(old); + } + // a lock of the new org, so unlock has something to (wrongly) lift; absent for the + // lock call itself, which would be refused as a duplicate + let is_lock = p.ends_with("/lock"); + sql(&app.db, "DELETE FROM org_locks", []); + if !is_lock { + lock_row(&app); + } + let (st, v) = send_bare(&app, m, p, body); + assert_eq!( + (st, v["error"].as_str()), + (409, Some("the org changed, reload")), + "{m} {p} with {stale:?}" + ); + assert_eq!( + count(&app.db, "SELECT COUNT(*) FROM org_locks", []), + i64::from(!is_lock), + "{m} {p}" + ); + } + } + assert_eq!(org_name(&app.db, org).as_deref(), Some("Newcomer")); + assert_eq!( + count(&app.db, "SELECT active FROM api_keys WHERE id=?", [kid]), + 1 + ); + assert_eq!( + count(&app.db, "SELECT COUNT(*) FROM password_resets", []), + 0 + ); + assert!(app.mail.all().is_empty()); + assert!(audit_rows(&app).is_empty()); + // the current generation goes through + let (st, _) = send( + &app, + "POST", + &format!("/operator/orgs/{org}/unlock"), + json!({}), + ); + assert_eq!(st, 200); +} + +// --- a lock holds only while the operator token is set, and only for its own org generation ----- + +/// A claimed job of `org` whose agent went quiet. +fn stale_claim(app: &App, org: i64) -> i64 { + let reg = register(&app.db, "pcs", "agent-key-s", &[decl("HP", true)], org); + let job = enqueue(&app.db, reg.pid("HP"), b"A", |j| j.org_id = Some(org)); + assert!(claim(&app.db, reg.computer_id).is_some()); + job +} + +#[test] +fn the_reaper_cancels_a_stale_claimed_job_of_a_locked_org() { + let app = app(); + let (org, _) = customer(&app.db, "Acme", "boss@acme.test"); + let (other, _) = customer(&app.db, "Other", "o@other.test"); + let job = stale_claim(&app, org); + let reg = register(&app.db, "pco", "agent-key-o", &[decl("HP", true)], other); + let theirs = enqueue(&app.db, reg.pid("HP"), b"B", |j| j.org_id = Some(other)); + assert!(claim(&app.db, reg.computer_id).is_some()); + let (st, _) = send( + &app, + "POST", + &format!("/operator/orgs/{org}/lock"), + json!({"reason": REASON}), + ); + assert_eq!(st, 200); + assert_eq!(state_of(&app.db, job).0, "claimed", "claimed jobs run on"); + printpapi_server::server::reaper_pass(&app.state, -1.0, 3); + assert_eq!( + state_of(&app.db, job), + ("cancelled".into(), Some("org locked".into())) + ); + assert_eq!( + state_of(&app.db, theirs).0, + "queued", + "other orgs are requeued as before" + ); +} + +#[test] +fn without_the_operator_token_a_lock_is_not_enforced() { + let hosted = app(); + let (org, _) = customer(&hosted.db, "Acme", "boss@acme.test"); + let (pid, key) = printer_and_key(&hosted.db, org); + let job = stale_claim(&hosted, org); + assert_eq!( + send( + &hosted, + "POST", + &format!("/operator/orgs/{org}/lock"), + json!({"reason": REASON}) + ) + .0, + 200 + ); + // the same database, started again without the token + let plain = App::on(hosted.db.clone(), |_| {}); + let r = submit_everywhere(&plain, org, pid, &key, 1); + assert_eq!(r[0].0, 200, "POST /jobs: {:?}", r[0]); + assert_eq!(r[1].0, 200, "POST /orders: {:?}", r[1]); + assert_eq!(r[3].0, 201, "PrintNode: {:?}", r[3]); + printpapi_server::server::reaper_pass(&plain.state, -1.0, 3); + assert_eq!(state_of(&plain.db, job).0, "queued"); + // with the token the lock holds again + let r = submit_everywhere(&hosted, org, pid, &key, 2); + assert_eq!(r[0].0, 403, "{:?}", r[0]); +} + +#[test] +fn a_lock_row_of_another_org_generation_locks_nothing_and_shows_nothing() { + let app = app(); + let (org, _) = customer(&app.db, "Acme", "boss@acme.test"); + let (pid, key) = printer_and_key(&app.db, org); + let created = created_of(&app.db, org).unwrap(); + sql( + &app.db, + "INSERT INTO org_locks(org_id, org_created_at, reason, locked_at) VALUES(?,?,?,?)", + rusqlite::params![org, created - 5.0, REASON, 2.0], + ); + let r = submit_everywhere(&app, org, pid, &key, 1); + assert_eq!(r[0].0, 200, "{:?}", r[0]); + assert_eq!(r[3].0, 201, "{:?}", r[3]); + let job = stale_claim(&app, org); + printpapi_server::server::reaper_pass(&app.state, -1.0, 3); + assert_eq!(state_of(&app.db, job).0, "queued"); + let d = op(&app, "GET", &format!("/operator/orgs/{org}")) + .send() + .json(); + assert_eq!(d["locked"], false, "{d}"); + assert_eq!(d["lock"], Value::Null, "{d}"); + assert_ne!(d["status"], "locked"); + let l = op(&app, "GET", "/operator/orgs").send().json(); + let row = l["orgs"] + .as_array() + .unwrap() + .iter() + .find(|o| o["id"] == org) + .unwrap(); + assert_eq!(row["locked"], false); + assert_ne!(row["status"], "locked"); + // a fresh lock replaces the stale row instead of being refused as a duplicate + let (st, _) = send( + &app, + "POST", + &format!("/operator/orgs/{org}/lock"), + json!({"reason": REASON}), + ); + assert_eq!(st, 200); + assert_eq!(submit_everywhere(&app, org, pid, &key, 3)[0].0, 403); +} + +#[test] +fn a_failed_mail_row_carries_the_org_generation() { + let app = app(); + let (org, user) = customer(&app.db, "Acme", "boss@acme.test"); + let created = created_of(&app.db, org).unwrap(); + *app.mail.fail.lock().unwrap() = true; + let (st, _) = send( + &app, + "POST", + &format!("/operator/users/{user}/reset"), + json!({"org_id": org}), + ); + assert_eq!(st, 502); + let (st, c) = send( + &app, + "POST", + "/operator/orgs", + json!({"name": "Fresh", "email": "fresh@fresh.test"}), + ); + assert_eq!(st, 200, "{c}"); + let rows = audit_rows(&app); + let failed = audit_of(&rows, "user.reset_mail_failed"); + assert_eq!(failed.len(), 2); + for f in &failed { + let want = if f["org_id"] == org { + created + } else { + created_of(&app.db, c["org_id"].as_i64().unwrap()).unwrap() + }; + assert_eq!(f["org_created_at"], want, "{f}"); + } +} diff --git a/crates/server/tests/store_compat.rs b/crates/server/tests/store_compat.rs index aa7e3eb..ad39cc6 100644 --- a/crates/server/tests/store_compat.rs +++ b/crates/server/tests/store_compat.rs @@ -291,7 +291,10 @@ fn expiring_and_reaping_python_rows() { ("failed", Some("expired")) ); // job 3 was claimed long ago and is stale - assert_eq!(requeue_stale(c, 60.0, 3, Some(BASE + 1000.0)).unwrap(), 1); + assert_eq!( + requeue_stale(c, 60.0, 3, Some(BASE + 1000.0), false).unwrap(), + 1 + ); assert_eq!(get_job(c, 3, None).unwrap().unwrap().state, "queued"); }); } diff --git a/docs/operator.md b/docs/operator.md index 21fbb6c..e9a6a98 100644 --- a/docs/operator.md +++ b/docs/operator.md @@ -182,6 +182,14 @@ commit. Bodies are JSON; the optional `reason` is a string of at most 500 charac the audit log, so keep customer data out of it. An org or id that does not exist answers `404`; a body that is not a JSON object, or a field that fails validation, answers `400` and changes nothing. +**Every write on an existing org names its generation.** Org and user ids are reused by SQLite after +the newest row is deleted, so an id alone does not say which customer a page showed. Each write +(`PUT`, `lock`, `unlock`, `DELETE` of an org, the user reset and the key revoke) carries +`org_created_at`, the `created_at` the read endpoints returned for that org, and the server compares +it with the org's `created_at` inside the transaction. A different or missing value answers **`409` +`the org changed, reload`**; nothing is changed, no audit row is written and no mail goes out. +`POST /operator/orgs` creates the org and takes none. + | Call | Audit action | |---|---| | `PUT /operator/orgs/{id}` | `org.update` | @@ -207,8 +215,9 @@ same body wins over the plan's. Answer: `{"ok": true}`. `POST /operator/orgs/{id}/lock` with `{reason}` of at least 8 characters inserts a row into the table `org_locks` (`org_id`, `org_created_at`, `reason`, `locked_at`) and cancels the org's queued -jobs (`error: "org locked"`; a job an agent already claimed runs on). Answer: -`{"ok": true, "cancelled_jobs": 3}`; `409` if the org is already locked. +jobs (`error: "org locked"`). A job an agent had already claimed is not interrupted; if that agent +goes quiet, the reaper cancels the job (`org locked`) instead of putting it back in the queue. +Answer: `{"ok": true, "cancelled_jobs": 3}`; `409` if the org is already locked. A lock is a **pure flag**: quota and plan stay as they are, so billing and quota writes need no change. While it is set, every way a job gets in answers **`403` `org locked`**: `POST /jobs`, @@ -217,13 +226,22 @@ next to the quota check in the enqueue path and again before any payload is down org causes no outbound request, and an idempotent resubmit does not get an old job back either. Logins, the dashboard and agents keep working, so the customer can see what is going on. +A lock row belongs to one org generation: it counts only while its `org_created_at` equals the +org's `created_at`. A row left by an earlier org of the same id locks nothing and shows nowhere. + +**Locks are enforced only while `PRINTAPI_OPERATOR_TOKEN` is set.** Without the token the whole +operator API is a `404`, so nothing could show or lift a lock; it is inert like the rest. The +submit check and the reaper rule above then do nothing, the rows stay in the database, and the server +prints one line at startup: `N org locks are not enforced: PRINTAPI_OPERATOR_TOKEN is unset`. Set the +token again and they hold again. + `POST /operator/orgs/{id}/unlock` (`{reason?}`) deletes the row; `409` if the org is not locked. `GET /operator/orgs` and the org detail show the lock (`locked`, `status: "locked"`, `lock`). > **Rolling back to an older version drops the lock.** Versions before this one (and the Python > server of v2.x) do not read `org_locks`: a locked org can submit again, and the table is kept -> untouched. Unlock first, or accept that. Deleting an org there also leaves its lock row behind, so -> a later org that reuses the id would still read as locked on a newer version. +> untouched. Unlock first, or accept that. Deleting an org there also leaves its lock row behind; a +> later org that reuses the id is not locked by it, because the row names the old org's generation. ### `DELETE /operator/orgs/{id}` @@ -245,12 +263,14 @@ the commit. Answer: `{"ok": true, "org_id", "user_id", "mail_sent"}`. Without ma ### `POST /operator/users/{id}/reset` `{org_id, reason?}` sends a password-reset mail to the user and never returns the token. `org_id` -must be the user's org (`409` otherwise), so a stale page cannot reach a user that reuses an id. `409` +must be the user's org (`409` otherwise) and `org_created_at` that org's generation (`409` +`the org changed, reload`), so a stale page cannot reach a user that reuses an id. `409` `mail is not configured` without mail and `PUBLIC_URL`; `502` if the mail did not go out (the row `user.reset_mail_failed` says so). A user without an e-mail address (the seeded legacy one) is `404`. ### `DELETE /operator/keys/{id}` -`{org_id, reason?}` revokes an API key (`409` if the key belongs to another org). Agents enrolled +`{org_id, org_created_at, reason?}` revokes an API key (`409` if the key belongs to another org or +generation). Agents enrolled with it end their long-poll with `401`. Removing a single user is not offered here: customers remove their own accounts, and root still can.