diff --git a/README.md b/README.md index 2b8b19e..7287afc 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, 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/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..5fe487a 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(), ) @@ -233,10 +287,20 @@ 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}"); } + 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}"))?; + 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, @@ -354,3 +418,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 f215689..3aad8c7 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,12 @@ 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() })) } @@ -629,6 +653,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()) { @@ -749,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), @@ -769,6 +805,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 @@ -781,7 +822,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)); } @@ -801,7 +849,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()), @@ -1048,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 { @@ -1065,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 @@ -1206,6 +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| { + 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)? { @@ -1217,6 +1300,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 { @@ -1321,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); @@ -1329,6 +1414,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)), } @@ -1370,6 +1456,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)), @@ -1445,6 +1532,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) @@ -1752,6 +1840,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 @@ -2257,7 +2346,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(); @@ -2298,10 +2387,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)), @@ -2377,15 +2468,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()); @@ -2650,6 +2735,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) => { @@ -2664,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 new file mode 100644 index 0000000..c17015b --- /dev/null +++ b/crates/server/src/server/operator.rs @@ -0,0 +1,732 @@ +// 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; + +/// The same paging bounds for the org and job lists. +const LIST_MAX_LIMIT: i64 = 200; +const LIST_DEFAULT_LIMIT: i64 = 50; + +/// 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, suffix) = match rest.split_once('/') { + Some((id, s @ ("jobs" | "lock" | "unlock"))) => (id, s), + Some(_) => return None, + None => (rest, ""), + }; + if id.is_empty() || !id.bytes().all(|b| b.is_ascii_digit()) { + return None; + } + 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. +/// 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) + .ok_or_else(|| jerr(400, "org_id required")) +} + +/// 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 + .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 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(), + ("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()), + }, + }; + r.unwrap_or_else(|e| { + eprintln!("internal error: {e}"); + jerr(500, "internal error") + }) + } + + /// `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)?)) + } + + /// 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 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(), + 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, 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(), + }, + ) + } + + 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, 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(), + }, + ) + } + + 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 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 + // 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(store::Refusal::OrgChanged) => org_changed(), + 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 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() + }; + 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 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()), + }; + let text = self.reset_mail_text( + "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() + }; + 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 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(), + }) + } + + 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> { + 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 f24fe3b..6037f11 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}"), } } @@ -388,6 +391,19 @@ 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); +-- 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] = &[ @@ -423,6 +439,15 @@ 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 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). @@ -565,15 +590,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 +700,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 +745,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 +811,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()? @@ -750,11 +844,11 @@ pub fn delete_org(conn: &Connection, org_id: i64) -> Result { "users", "label_templates", "terms_acceptances", + "org_locks", ] { 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 +1093,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 +1150,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 +1192,6 @@ pub fn signup( params![org_id, user_id, version, now], )?; } - tx.commit()?; Ok(Signup { org_id, user_id }) } @@ -1116,16 +1236,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) } @@ -1313,6 +1444,37 @@ 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 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(); + 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 @@ -1349,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!( @@ -1371,6 +1543,10 @@ 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 + 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. @@ -1531,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 >= ?", @@ -1572,7 +1760,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. @@ -2090,6 +2278,853 @@ 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 + ], + ) + // 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()) +} + +/// 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::>()?) +} + +// --- 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 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. +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) + }) + .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, + seen: Option, + 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); + }; + if seen != Some(created) { + return Ok(Outcome::Refused(Refusal::OrgChanged)); + } + 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, + 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], + )?; + 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, + 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 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( + &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, + seen: Option, + 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 seen != Some(created) { + return Ok(Outcome::Refused(Refusal::OrgChanged)); + } + 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, + seen: Option, + 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)); + } + 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: created, + 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, + seen: Option, + 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)); + } + 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: created, + 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 +// 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 + 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 + 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 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 { + 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 { + 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::*; @@ -2431,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"); @@ -2443,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"); @@ -2860,6 +3895,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] @@ -3306,6 +4398,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/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/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..0341e92 --- /dev/null +++ b/crates/server/tests/http_operator.rs @@ -0,0 +1,1117 @@ +// 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); +} + +// --- 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}" + ); + // /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()); + 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) \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}"); + 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) \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!( + 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/http_operator_writes.rs b/crates/server/tests/http_operator_writes.rs new file mode 100644 index 0000000..3f42a44 --- /dev/null +++ b/crates/server/tests/http_operator_writes.rs @@ -0,0 +1,1570 @@ +// 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) +} + +/// 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()); +} + +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) SELECT id, created_at, ?, ? FROM orgs WHERE id=?", + rusqlite::params![REASON, 2.0, org], + ); + 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:?}" + ); + } +} + +// --- 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 0ada047..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"); }); } @@ -366,6 +369,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 +418,75 @@ 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" + ] + ); + 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); + 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/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 new file mode 100644 index 0000000..e9a6a98 --- /dev/null +++ b/docs/operator.md @@ -0,0 +1,276 @@ +# 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, 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 + +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. + +## 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. + +## 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. + +**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` | +| `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 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`, +`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. + +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; 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}` + +`{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) 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, 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. diff --git a/docs/server.md b/docs/server.md index 90ed9f5..c3e34e7 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 (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 PRINTAPI_TOKEN=change-me PRINT_DB=data/printpapi.db ./printpapi