Skip to main content

cpa_server/
management.rs

1//! Management API (v8, plus the few legacy v0 reads the dashboard predates).
2//!
3//! Routing follows gin: an unknown path or an unregistered method on a known path is a
4//! bare 404 that never reaches authentication. Access rules live in [`access`].
5use std::path::PathBuf;
6use std::sync::{Arc, Mutex, PoisonError};
7
8use axum::body::Bytes;
9use axum::extract::rejection::BytesRejection;
10use axum::extract::{DefaultBodyLimit, OriginalUri, State};
11use axum::handler::Handler;
12use axum::http::{HeaderMap, HeaderValue, Method, StatusCode, header};
13use axum::response::{IntoResponse, Response};
14use axum::routing::{MethodRouter, any, get};
15use axum::{Router, middleware};
16use cpa_common::gostr::GoStr;
17use cpa_core::config::{Config, ConfigDocument, archive_comments, credentials, is_bcrypt};
18use cpa_core::credential::{Credential, Source};
19use serde_json::{Value, json};
20
21use crate::Runtime;
22use crate::scheduler::{ErrorRule, Policy};
23
24mod access;
25mod api_call;
26mod auth_files;
27mod auth_index;
28mod iso_currency;
29pub(crate) mod legacy;
30mod logs;
31pub(crate) mod multipart;
32mod oauth;
33pub mod observability;
34mod plugin_auth;
35mod plugin_oauth;
36mod plugin_store;
37mod plugins;
38pub(crate) mod quota;
39mod quota_probe;
40mod siwc;
41pub use access::cors;
42pub(crate) use access::{Cors, cors_headers};
43pub(crate) use plugins::go_query;
44
45pub struct Management {
46    pub(crate) rt: Arc<Runtime>,
47    pub(crate) path: PathBuf,
48    // ponytail: one lock for config and auth disk operations; split only if management
49    // throughput matters. The watcher shares it, preventing stale disk publication.
50    pub(crate) disk: Mutex<()>,
51    /// Uploaded files no synthesizer claims, kept listed until restart like Go's
52    /// fallback auths (see `credentials::upload_fallback`).
53    pub(crate) fallbacks: Mutex<std::collections::BTreeSet<PathBuf>>,
54    /// Credentials disabled through the status or fields endpoints: Go's in-memory
55    /// auth then reports `disabled via management API` until re-enabled.
56    pub(crate) disabled_via_api: Mutex<std::collections::BTreeSet<String>>,
57    /// When runtime-only credentials were first seen and last changed (Go's
58    /// `CreatedAt`/`UpdatedAt` for them; the store keeps no timestamps).
59    pub(crate) runtime_seen: Mutex<std::collections::HashMap<String, auth_files::RuntimeSeen>>,
60    /// Go net/http clients by proxy for `api-call`.
61    pub(crate) clients: cpa_exec::proxy::GoClients,
62    pub(crate) latest_release_url: std::borrow::Cow<'static, str>,
63    pub(crate) update_check_disabled: bool,
64    // No task or expiry timer: allocated only after a successful, explicit check.
65    // Wall-clock time, so a cached result also expires across sleep or hibernation.
66    pub(crate) latest_release: tokio::sync::Mutex<Option<(std::time::SystemTime, String)>>,
67    /// Pending and recent management logins (Go `oauthSessionStore`).
68    pub(crate) oauth: oauth::Sessions,
69    /// Callback forwarders by port (Go `callbackForwarders`).
70    pub(crate) forwarders: Mutex<std::collections::HashMap<u16, oauth::Forwarder>>,
71    pub(crate) login_base: Option<String>,
72    /// Told the state of every management login that has finished (tests only).
73    pub(crate) login_settled: Option<tokio::sync::mpsc::UnboundedSender<String>>,
74    /// Every login worker panics on its blocking save task (tests only).
75    pub(crate) login_panic: bool,
76    /// Go `Handler.logDir`: resolved once at startup.
77    pub(crate) log_dir: PathBuf,
78    /// The remote store mirroring config and auth files, when one is configured.
79    pub(crate) store: Option<Arc<dyn crate::persist::StorePersister>>,
80    /// Pins auth-dir across reloads (tests only; see [`Options::auth_dir`]).
81    auth_dir: Option<PathBuf>,
82    /// The zone log line timestamps are parsed in (Go `time.Local` when `None`).
83    pub(crate) log_zone: logs::Zone,
84    /// Plugin store test seams and release cache (Go `Handler.pluginStore*`).
85    pub(crate) plugin_store: plugin_store::StoreState,
86    access: access::Access,
87}
88
89#[derive(Default)]
90pub struct Options {
91    /// `--password`: accepted from loopback clients only, like Go's local password.
92    pub local_password: String,
93    /// `-tui -standalone`: the local password alone keeps management on, across
94    /// reloads, for loopback clients. Go refuses every request without a configured
95    /// secret, so its standalone TUI cannot sign in with a keyless config.
96    pub standalone: bool,
97    /// Overrides the `MANAGEMENT_PASSWORD` environment variable when set.
98    pub management_password: Option<String>,
99    /// Overrides [`observability::LATEST_RELEASE_URL`] (tests point it at a local server).
100    pub latest_release_url: Option<String>,
101    /// Overrides CLIPROXY_NO_UPDATE_CHECK (tests only).
102    pub update_check_disabled: Option<bool>,
103    /// One local base URL for every provider's login endpoints (tests only).
104    pub login_base: Option<String>,
105    /// Receives the state of every management login once its worker has finished,
106    /// saved, failed or cancelled (tests only).
107    pub login_settled: Option<tokio::sync::mpsc::UnboundedSender<String>>,
108    /// Every management login worker panics on its blocking save task (tests only).
109    pub login_panic: bool,
110    /// Overrides the log directory Go resolves at startup (tests only).
111    pub log_dir: Option<PathBuf>,
112    /// A Postgres, git or object store mirroring config and auth files (Go's
113    /// registered token store when it persists remotely).
114    pub store: Option<Arc<dyn crate::persist::StorePersister>>,
115    /// Parses log line timestamps in this zone instead of the local one (tests only).
116    pub log_zone: Option<chrono::FixedOffset>,
117    /// Scans this directory for credentials on every reload instead of the config's
118    /// auth-dir, so a config without one never reads the default `~/.cli-proxy-api`
119    /// (tests only). A configured store still wins.
120    pub auth_dir: Option<PathBuf>,
121    /// The only plugin store registry (Go `pluginStoreRegistryURL`; tests only).
122    pub plugin_store_registry_url: Option<String>,
123    /// The plugin store's HTTP client (Go `pluginStoreHTTPClient`; tests only).
124    pub plugin_store_http: Option<Arc<dyn cpa_plugin::store::Doer>>,
125    /// The plugin store's GitHub rate limiter (Go `pluginStoreRateLimiter`); the
126    /// process-wide one when unset.
127    pub plugin_store_rate_limiter: Option<Arc<cpa_plugin::store::GitHubRateLimiter>>,
128}
129
130impl Management {
131    /// Go `managementRoutesEnabled`, for the RESP protocol on the main listener.
132    pub(crate) fn routes_enabled(&self) -> bool {
133        self.access.available()
134    }
135
136    /// Go `AuthenticateManagementKey` for callers outside HTTP (the RESP protocol).
137    pub(crate) async fn authenticate_key(
138        &self,
139        ip: &str,
140        local: bool,
141        provided: &[u8],
142    ) -> Result<(), (StatusCode, String)> {
143        self.access.authenticate(&self.rt.config(), ip, local, provided).await
144    }
145
146    pub fn new(rt: Arc<Runtime>, path: PathBuf) -> Arc<Self> {
147        Self::with_options(rt, path, Options::default())
148    }
149
150    /// Captures startup-only settings (trusted proxies, environment secret) and
151    /// publishes the scheduler policy derived from the current config.
152    pub fn with_options(rt: Arc<Runtime>, path: PathBuf, options: Options) -> Arc<Self> {
153        let cfg = rt.config();
154        rt.publish_policy(policy(&cfg));
155        let latest_release_url = options
156            .latest_release_url
157            .clone()
158            .map(std::borrow::Cow::Owned)
159            .unwrap_or(std::borrow::Cow::Borrowed(observability::LATEST_RELEASE_URL));
160        let update_check_disabled = options
161            .update_check_disabled
162            .unwrap_or_else(|| std::env::var("CLIPROXY_NO_UPDATE_CHECK").is_ok_and(|v| v == "1"));
163        let login_base = options.login_base.clone();
164        let log_dir = options
165            .log_dir
166            .clone()
167            .unwrap_or_else(|| crate::logging::resolve_log_dir(&cfg));
168        let mut options = options;
169        let store = options.store.take();
170        let auth_dir = options.auth_dir.take();
171        let login_settled = options.login_settled.take();
172        let login_panic = options.login_panic;
173        let log_zone = options.log_zone;
174        let plugin_store = plugin_store::StoreState::new(
175            options.plugin_store_registry_url.take(),
176            options.plugin_store_http.take(),
177            options.plugin_store_rate_limiter.take(),
178        );
179        let access = access::Access::new(&cfg, options);
180        rt.usage_queue().configure(access.available(), &cfg);
181        let state = Arc::new(Self {
182            access,
183            rt,
184            path,
185            disk: Mutex::new(()),
186            fallbacks: Mutex::default(),
187            disabled_via_api: Mutex::default(),
188            runtime_seen: Mutex::default(),
189            clients: cpa_exec::proxy::GoClients::new(cpa_exec::proxy::Hooks::default()),
190            latest_release_url,
191            update_check_disabled,
192            latest_release: tokio::sync::Mutex::new(None),
193            oauth: oauth::Sessions::default(),
194            forwarders: Mutex::default(),
195            login_base,
196            login_settled,
197            login_panic,
198            log_dir,
199            store,
200            auth_dir,
201            log_zone,
202            plugin_store,
203        });
204        oauth::install_callback_sink(&state);
205        access::start_purge(&state);
206        plugin_auth::attach(&state);
207        state
208    }
209
210    /// Go `Watcher.mirroredAuthDir`: with a remote store, the auth directory is the
211    /// store's mirror whatever `auth-dir` says.
212    pub(crate) fn lock_auth_dir(&self, cfg: &mut Config) {
213        if let Some(store) = &self.store {
214            cfg.auth_dir = store.auth_dir();
215        } else if let Some(dir) = &self.auth_dir {
216            cfg.auth_dir = dir.clone();
217        }
218    }
219
220    /// Go `deleteTokenRecord`: tells the store about an explicit removal. Blocking;
221    /// call from a blocking thread.
222    pub(crate) fn store_delete(&self, path: &std::path::Path) -> Result<(), String> {
223        let Some(store) = self.store.clone() else {
224            return Ok(());
225        };
226        let path = std::path::absolute(path).unwrap_or_else(|_| path.to_path_buf());
227        store.delete_auth(path).map_err(|e| format!("{e:#}"))
228    }
229
230    /// [`Self::store_delete`] only while the file still holds `expected` (or is gone),
231    /// checked by the store after it syncs. Returns whether it deleted.
232    pub(crate) fn store_delete_unchanged(&self, path: &std::path::Path, expected: &[u8]) -> Result<bool, String> {
233        let Some(store) = self.store.clone() else {
234            return Ok(false);
235        };
236        let path = std::path::absolute(path).unwrap_or_else(|_| path.to_path_buf());
237        store
238            .delete_auth_unchanged(path, expected)
239            .map_err(|e| format!("{e:#}"))
240    }
241
242    /// Go `Store.Save`: `write` through the configured store, which has the file when
243    /// this returns (git syncs first and holds its lock across the write); without a
244    /// store, just `write`. Blocking: call from a blocking thread holding `disk`.
245    pub(crate) fn store_write(&self, write: crate::persist::SaveFn<'_>) -> Result<Option<PathBuf>, String> {
246        match &self.store {
247            Some(store) => store.save_auth(write),
248            None => write(),
249        }
250        .map_err(|e| format!("{e:#}"))
251    }
252
253    /// Publishes a config and everything Go derives from it on reload: scheduler
254    /// policy, management availability, and the credential set (auth-dir files plus
255    /// config API keys). `files` replaces the auth-dir scan when the caller already
256    /// has one; its file hashes keep a stale scan from undoing a later write (Go
257    /// c4c1d43e). Callers hold `disk`. Infallible on purpose: access settings of a
258    /// valid config (a rotated or removed secret) always take effect.
259    pub(crate) fn publish(&self, cfg: Config, files: Option<credentials::AuthScan>) {
260        self.publish_upload(cfg, files, None);
261    }
262
263    /// [`Self::publish`] after an upload wrote `upload`'s file. While plugin auth
264    /// providers have not parsed the new bytes, the uploaded credential is registered as
265    /// built, as Go's upload registers it (`buildAuthFromFileData`, no plugin parser),
266    /// replacing one with the same ID; the watcher's next reload asks the plugins.
267    /// `upload` carries the SHA-256 of the bytes written: a write committed since (a
268    /// token refresh) changed the file, and the current credential is kept.
269    pub(crate) fn publish_upload(
270        &self,
271        cfg: Config,
272        files: Option<credentials::AuthScan>,
273        upload: Option<(Credential, [u8; 32])>,
274    ) {
275        // Nothing below is applied for a config the runtime would refuse to publish.
276        if !Runtime::accepts_config(&cfg) {
277            return;
278        }
279        let mut cfg = cfg;
280        self.lock_auth_dir(&mut cfg);
281        use sha2::{Digest, Sha256};
282        let scan = files.unwrap_or_else(|| credentials::scan_auth_dir(&cfg));
283        let mut all = scan.credentials;
284        let mut read = scan.read;
285        // Uploads record absolute paths; a relative auth-dir scans relative ones.
286        let absolute = |p: &PathBuf| std::path::absolute(p).unwrap_or_else(|_| p.clone());
287        // Fallbacks follow their file: gone with it, replaced once a synthesizer
288        // claims it, otherwise rebuilt from its current content.
289        let mut claimed = Vec::new();
290        let mut fallbacks = self.fallbacks.lock().unwrap_or_else(PoisonError::into_inner);
291        fallbacks.retain(|path| {
292            let Ok(data) = std::fs::read(path) else { return false };
293            if all
294                .iter()
295                .any(|c| matches!(&c.source, Source::File(p) if absolute(p) == absolute(path)))
296            {
297                claimed.push(path.clone());
298                return false;
299            }
300            match credentials::upload_fallback(&cfg.auth_dir, path, &data) {
301                Some(c) => {
302                    // Bound to the bytes it was built from, under its own path, so the
303                    // freshness check compares this read, not the scan's.
304                    if let Source::File(p) = &c.source {
305                        read.insert(p.clone(), Sha256::digest(&data).into());
306                    }
307                    all.push(c);
308                    true
309                }
310                None => false,
311            }
312        });
313        drop(fallbacks);
314        #[cfg(test)]
315        {
316            let mut hooks = BEFORE_RECONCILE.lock().unwrap();
317            let hook = hooks
318                .iter()
319                .position(|(dir, _)| *dir == cfg.auth_dir)
320                .map(|i| hooks.remove(i).1);
321            drop(hooks);
322            if let Some(hook) = hook {
323                hook();
324            }
325        }
326        all.extend(credentials::from_config(&cfg));
327        self.access.config_published(&cfg);
328        crate::logging::configure(&cfg);
329        self.rt.usage_queue().configure(self.access.available(), &cfg);
330        let policy = policy(&cfg);
331        self.rt.publish_config_and_policy(cfg, policy);
332        let upload = upload.filter(|(c, _)| {
333            matches!(&c.source, Source::File(path) if scan.deferred.iter().any(|p| absolute(p) == absolute(path)))
334        });
335        if let Some((
336            Credential {
337                source: Source::File(path),
338                ..
339            },
340            written,
341        )) = &upload
342        {
343            read.insert(path.clone(), *written);
344        }
345        let rejected = self.rt.store().reconcile_scanned_with(all, &read, |current, all| {
346            crate::plugins::keep_deferred(current, all, &scan.deferred);
347            if let Some((upload, _)) = upload {
348                all.retain(|c| c.id != upload.id);
349                all.push(upload);
350            }
351        });
352        // A synthesizer claimed the file but its credential was rejected as stale, so the
353        // fallback stays live: keep tracking it, or the next reload would drop it.
354        let kept: Vec<PathBuf> = claimed
355            .into_iter()
356            .filter(|path| rejected.iter().any(|r| absolute(r) == absolute(path)))
357            .collect();
358        if !kept.is_empty() {
359            self.fallbacks
360                .lock()
361                .unwrap_or_else(PoisonError::into_inner)
362                .extend(kept);
363        }
364        // Go's watcher calls redisqueue.NotifyUsageRefresh after every client reload.
365        self.rt.usage_queue().notify_usage_refresh();
366    }
367}
368
369/// `Policy::from(routing)` plus the provider-level rules Go reads from config:
370/// `oauth.request-scoped-errors`, sanitized like `SanitizeOAuthRequestScopedErrors`.
371pub fn policy(cfg: &Config) -> Policy {
372    let mut policy = Policy::from(&cfg.routing);
373    let rules = cfg
374        .document
375        .get("oauth")
376        .and_then(|o| o.get("request-scoped-errors"))
377        .and_then(serde_yaml_ng::Value::as_mapping);
378    for (channel, list) in rules.into_iter().flatten() {
379        let channel = channel.as_str().unwrap_or_default().trim().go_lower();
380        let clean: Vec<ErrorRule> = list
381            .as_sequence()
382            .into_iter()
383            .flatten()
384            .filter_map(|r| {
385                let words = |k: &str| -> Vec<String> {
386                    r.get(k)
387                        .and_then(serde_yaml_ng::Value::as_sequence)
388                        .into_iter()
389                        .flatten()
390                        .filter_map(|v| v.as_str().map(|s| s.trim().to_owned()))
391                        .filter(|s| !s.is_empty())
392                        .collect()
393                };
394                let rule = ErrorRule {
395                    status: r.get("status").and_then(serde_yaml_ng::Value::as_i64).unwrap_or(0),
396                    r#match: words("match"),
397                    match_regex: words("match-regexr"),
398                    action: r
399                        .get("action")
400                        .and_then(serde_yaml_ng::Value::as_str)
401                        .unwrap_or_default()
402                        .trim()
403                        .go_lower(),
404                };
405                (rule.status > 0
406                    && !(rule.r#match.is_empty() && rule.match_regex.is_empty())
407                    && !rule.action.is_empty())
408                .then_some(rule)
409            })
410            .collect();
411        if !channel.is_empty() && !clean.is_empty() {
412            policy.oauth_request_scoped_errors.insert(channel, clean);
413        }
414    }
415    policy
416}
417
418/// gin `c.JSON` of a `gin.H` map: Go's `json.Marshal` (sorted keys; `<`, `>`, `&`,
419/// U+2028 and U+2029 escaped) with the charset parameter.
420pub(crate) fn json(status: StatusCode, value: &Value) -> Response {
421    json_body(status, crate::gojson::sorted(value))
422}
423
424/// gin `c.JSON` of a value that holds Go structs: objects keep their insertion order
425/// (struct fields as Go declares them; callers insert map levels sorted, see
426/// [`sorted_keys`]), strings escaped like `json.Marshal`.
427pub(crate) fn json_ordered(status: StatusCode, value: &Value) -> Response {
428    let mut out = Vec::new();
429    write_ordered(value, &mut out);
430    json_body(status, String::from_utf8(out).expect("JSON text is UTF-8"))
431}
432
433fn write_ordered(value: &Value, out: &mut Vec<u8>) {
434    match value {
435        Value::Null => out.extend_from_slice(b"null"),
436        Value::Bool(b) => out.extend_from_slice(if *b { b"true" } else { b"false" }),
437        Value::Number(n) => out.extend_from_slice(n.to_string().as_bytes()),
438        Value::String(s) => out.extend(cpa_common::json::quote(s)),
439        Value::Array(items) => {
440            out.push(b'[');
441            for (i, item) in items.iter().enumerate() {
442                if i > 0 {
443                    out.push(b',');
444                }
445                write_ordered(item, out);
446            }
447            out.push(b']');
448        }
449        Value::Object(map) => {
450            out.push(b'{');
451            for (i, (key, item)) in map.iter().enumerate() {
452                if i > 0 {
453                    out.push(b',');
454                }
455                out.extend(cpa_common::json::quote(key));
456                out.push(b':');
457                write_ordered(item, out);
458            }
459            out.push(b'}');
460        }
461    }
462}
463
464/// A copy whose objects all have sorted keys, as Go encodes a `map[string]any`.
465pub(crate) fn sorted_keys(value: &Value) -> Value {
466    match value {
467        Value::Object(map) => {
468            let sorted: std::collections::BTreeMap<&String, Value> =
469                map.iter().map(|(k, v)| (k, sorted_keys(v))).collect();
470            Value::Object(sorted.into_iter().map(|(k, v)| (k.clone(), v)).collect())
471        }
472        Value::Array(items) => Value::Array(items.iter().map(sorted_keys).collect()),
473        other => other.clone(),
474    }
475}
476
477fn json_body(status: StatusCode, body: String) -> Response {
478    (
479        status,
480        [(
481            header::CONTENT_TYPE,
482            HeaderValue::from_static("application/json; charset=utf-8"),
483        )],
484        body,
485    )
486        .into_response()
487}
488
489pub(crate) fn json_error(status: StatusCode, message: &str) -> Response {
490    json(status, &json!({"error": message}))
491}
492
493/// Go `HTTPStatusFromErrorOr(err, 400)` for a failed body read in the handlers
494/// dd7b4334 changed: 413 at `server.max-request-body-bytes` (and at a route's own
495/// `DefaultBodyLimit`), else 400.
496pub(crate) fn read_status(rejection: &BytesRejection) -> StatusCode {
497    if crate::body_limit::is_too_large(rejection) || rejection.status() == StatusCode::PAYLOAD_TOO_LARGE {
498        StatusCode::PAYLOAD_TOO_LARGE
499    } else {
500        StatusCode::BAD_REQUEST
501    }
502}
503
504/// The text of a failed body read: Go's `err.Error()` at the limit.
505pub(crate) fn read_reason(rejection: &BytesRejection) -> String {
506    crate::claude::read_error(rejection).1
507}
508
509fn error(code: u16, message: &str) -> Response {
510    json_error(StatusCode::from_u16(code).unwrap(), message)
511}
512
513/// Wraps one method handler in the management guard; methods without a handler fall
514/// through to a bare 404 like gin's NoRoute.
515macro_rules! guarded {
516    ($state:expr, $handler:expr) => {
517        $handler.layer(middleware::from_fn_with_state($state.clone(), access::guard))
518    };
519}
520
521/// Availability only, no key: Go's OAuth callback routes.
522macro_rules! open {
523    ($state:expr, $handler:expr) => {
524        $handler.layer(middleware::from_fn_with_state($state.clone(), access::available))
525    };
526}
527
528/// gin answers HEAD and unregistered methods on a known path with NoRoute (no `Allow`
529/// header; starting from `any` keeps axum from adding one). Go's NoRoute serves
530/// plugin routes, so those requests go to [`plugins::no_route`].
531fn methods() -> MethodRouter<Arc<Management>> {
532    // An explicit HEAD keeps axum from answering HEAD with the GET handler.
533    any(plugins::no_route).head(plugins::no_route)
534}
535
536/// The OAuth callback POST needs no key, so unlike Go it keeps a bound: legitimate
537/// bodies are a state, a code and a redirect URL.
538const CALLBACK_BODY_LIMIT: usize = 64 * 1024;
539
540pub fn router(state: Arc<Management>) -> Router {
541    let s = &state;
542    let v8 = "/v8/management";
543    let v0 = "/v0/management";
544    let config_methods = || {
545        methods()
546            .get(guarded!(s, config))
547            .put(guarded!(s, config))
548            .patch(guarded!(s, config))
549            .delete(guarded!(s, config))
550    };
551    let mut router = Router::new()
552        .route(
553            &format!("{v8}/config"),
554            methods()
555                .get(guarded!(s, config))
556                .put(guarded!(s, config))
557                .patch(guarded!(s, config)),
558        )
559        .route(
560            &format!("{v8}/config.yaml"),
561            methods().get(guarded!(s, config)).put(guarded!(s, config)),
562        )
563        .route(&format!("{v8}/config/"), config_methods())
564        .route(&format!("{v8}/config/{{*path}}"), config_methods())
565        .route(
566            &format!("{v0}/config.yaml"),
567            methods()
568                .get(guarded!(s, legacy_yaml))
569                .put(guarded!(s, legacy::put_config_yaml)),
570        );
571    // v8 and its deprecated v0 spellings share Go's handlers.
572    for (base, files, definitions) in [
573        (v8, "credentials", "routing/model-definitions"),
574        (v0, "auth-files", "model-definitions"),
575    ] {
576        router = router
577            .route(
578                &format!("{base}/{files}"),
579                methods()
580                    .get(guarded!(s, auth_files::list))
581                    .post(guarded!(s, auth_files::upload))
582                    .delete(guarded!(s, auth_files::delete)),
583            )
584            .route(
585                &format!("{base}/{files}/models"),
586                methods().get(guarded!(s, auth_files::models)),
587            )
588            .route(
589                &format!("{base}/{files}/download"),
590                methods().get(guarded!(s, auth_files::download)),
591            )
592            .route(
593                &format!("{base}/{files}/status"),
594                methods().patch(guarded!(s, auth_files::status)),
595            )
596            .route(
597                &format!("{base}/{files}/fields"),
598                methods().patch(guarded!(s, auth_files::fields)),
599            )
600            .route(
601                &format!("{base}/{files}/refresh"),
602                methods().post(guarded!(s, auth_files::refresh)),
603            )
604            .route(
605                &format!("{base}/{definitions}/{{channel}}"),
606                methods().get(guarded!(s, auth_files::model_definitions)),
607            );
608    }
609    for (path, route) in [
610        (
611            "server/latest-version",
612            methods().get(guarded!(s, observability::latest_version)),
613        ),
614        ("requests/api-call", methods().post(guarded!(s, api_call::api_call))),
615        (
616            "routing/cooldown/reset",
617            methods().post(guarded!(s, auth_files::cooldown_reset)),
618        ),
619        (
620            "observability/usage/api-keys",
621            methods().get(guarded!(s, observability::api_key_usage)),
622        ),
623        (
624            "observability/usage/queue",
625            methods().get(guarded!(s, observability::usage_queue)),
626        ),
627        ("oauth/auth-url", methods().get(guarded!(s, oauth::auth_url))),
628        ("oauth/status", methods().get(guarded!(s, oauth::status))),
629        ("oauth/session", methods().delete(guarded!(s, oauth::cancel))),
630        ("oauth/import", methods().post(guarded!(s, oauth::import))),
631        ("oauth/siwc/bind", methods().post(guarded!(s, siwc::bind))),
632        (
633            "observability/logs",
634            methods()
635                .get(guarded!(s, logs::get_logs))
636                .delete(guarded!(s, logs::delete_logs)),
637        ),
638        (
639            "observability/logs/errors",
640            methods().get(guarded!(s, logs::error_logs)),
641        ),
642        (
643            "observability/logs/errors/{name}",
644            methods().get(guarded!(s, logs::download_error_log)),
645        ),
646        (
647            "observability/logs/requests/{id}",
648            methods().get(guarded!(s, logs::request_log)),
649        ),
650        (
651            "oauth/callback",
652            methods()
653                .get(open!(s, oauth::callback_get))
654                .post(open!(s, oauth::callback_post).layer(DefaultBodyLimit::max(CALLBACK_BODY_LIMIT))),
655        ),
656    ] {
657        router = router.route(&format!("{v8}/{path}"), route);
658    }
659    for (path, route) in [
660        (
661            "latest-version",
662            methods().get(guarded!(s, observability::latest_version)),
663        ),
664        ("api-call", methods().post(guarded!(s, api_call::api_call))),
665        ("reset-quota", methods().post(guarded!(s, auth_files::cooldown_reset))),
666        (
667            "api-key-usage",
668            methods().get(guarded!(s, observability::api_key_usage)),
669        ),
670        ("usage-queue", methods().get(guarded!(s, observability::usage_queue))),
671        ("get-auth-status", methods().get(guarded!(s, oauth::status))),
672        ("oauth-session", methods().delete(guarded!(s, oauth::cancel))),
673        (
674            "oauth-callback",
675            methods()
676                .get(open!(s, oauth::callback_get))
677                .post(open!(s, oauth::callback_post).layer(DefaultBodyLimit::max(CALLBACK_BODY_LIMIT))),
678        ),
679    ] {
680        router = router.route(&format!("{v0}/{path}"), route);
681    }
682    // Plugin routes: v8 and the v0 spellings Go keeps (internal/api/server_management.go,
683    // server_management_v8.go); the v0 config, enable and v8 store routes share them.
684    for (path, route) in [
685        ("plugins", methods().get(guarded!(s, plugins::list))),
686        ("plugins/{id}", methods().delete(guarded!(s, plugins::delete))),
687    ] {
688        router = router
689            .route(&format!("{v8}/{path}"), route.clone())
690            .route(&format!("{v0}/{path}"), route);
691    }
692    // Plugin store (plugin_store.go). gin keeps one route tree per method, so a DELETE of
693    // `plugins/store` is DeletePlugin with the ID `store`.
694    router = router
695        .route(
696            &format!("{v8}/plugins/store"),
697            methods()
698                .get(guarded!(s, plugin_store::list))
699                .delete(guarded!(s, plugins::delete_store_id)),
700        )
701        .route(
702            &format!("{v8}/plugins/store/{{id}}/install"),
703            methods().post(guarded!(s, plugin_store::install)),
704        )
705        .route(
706            &format!("{v0}/plugin-store"),
707            methods().get(guarded!(s, plugin_store::list)),
708        )
709        .route(
710            &format!("{v0}/plugin-store/{{id}}/install"),
711            methods().post(guarded!(s, plugin_store::install)),
712        );
713    // Plugin quota (plugin_quota.go): per-plugin under v8 and v0, the credential-level
714    // routes and the reset alias only under v0.
715    for base in [v8, v0] {
716        router = router.route(
717            &format!("{base}/plugins/{{id}}/quota"),
718            methods()
719                .get(guarded!(s, quota::get_plugin))
720                .post(guarded!(s, quota::fetch_plugin))
721                .delete(guarded!(s, quota::reset_plugin)),
722        );
723    }
724    router = router
725        .route(
726            &format!("{v0}/plugins/{{id}}/quota/reset"),
727            methods().post(guarded!(s, quota::reset_plugin)),
728        )
729        .route(
730            &format!("{v0}/quota/providers"),
731            methods().get(guarded!(s, quota::providers)),
732        )
733        .route(&format!("{v0}/quota/fetch"), methods().post(guarded!(s, quota::fetch)))
734        .route(&format!("{v0}/quota/reset"), methods().post(guarded!(s, quota::reset)));
735    router = router
736        .route(
737            &format!("{v0}/plugins/{{id}}/enabled"),
738            methods().patch(guarded!(s, plugins::patch_enabled)),
739        )
740        .route(
741            &format!("{v0}/plugins/{{id}}/config"),
742            methods()
743                .get(guarded!(s, plugins::get_config))
744                .put(guarded!(s, plugins::put_config))
745                .patch(guarded!(s, plugins::patch_config)),
746        );
747    // Go's remaining v0 routes, adapted over the v8 handlers (management/legacy.rs).
748    router = router.route(&format!("{v0}/config"), methods().get(guarded!(s, legacy::config)));
749    for path in legacy::FIELD_ROUTES {
750        let mut route = methods()
751            .get(guarded!(s, legacy::field_route))
752            .put(guarded!(s, legacy::field_route))
753            .patch(guarded!(s, legacy::field_route));
754        if path == "proxy-url" {
755            route = route.delete(guarded!(s, legacy::field_route));
756        }
757        router = router.route(&format!("{v0}/{path}"), route);
758    }
759    router = router.route(
760        &format!("{v0}/api-keys"),
761        methods()
762            .get(guarded!(s, legacy::api_keys))
763            .put(guarded!(s, legacy::api_keys))
764            .patch(guarded!(s, legacy::api_keys))
765            .delete(guarded!(s, legacy::api_keys)),
766    );
767    for path in legacy::LIST_ROUTES {
768        router = router.route(
769            &format!("{v0}/{path}"),
770            methods()
771                .get(guarded!(s, legacy::list_route))
772                .put(guarded!(s, legacy::list_route))
773                .patch(guarded!(s, legacy::list_route))
774                .delete(guarded!(s, legacy::list_route)),
775        );
776    }
777    for (path, _) in legacy::AUTH_URL_ROUTES {
778        router = router.route(&format!("{v0}/{path}"), methods().get(guarded!(s, legacy::auth_url)));
779    }
780    router = router
781        .route(
782            &format!("{v0}/vertex/import"),
783            methods().post(guarded!(s, legacy::vertex_import)),
784        )
785        .route(
786            &format!("{v0}/logs"),
787            methods()
788                .get(guarded!(s, logs::get_logs))
789                .delete(guarded!(s, logs::delete_logs)),
790        )
791        .route(
792            &format!("{v0}/request-error-logs"),
793            methods().get(guarded!(s, logs::error_logs)),
794        )
795        .route(
796            &format!("{v0}/request-error-logs/{{name}}"),
797            methods().get(guarded!(s, logs::download_error_log)),
798        )
799        .route(
800            &format!("{v0}/request-log-by-id/{{id}}"),
801            methods().get(guarded!(s, logs::request_log)),
802        );
803    router
804        .fallback(plugins::no_route)
805        .route("/management.html", get(panel))
806        .route("/assets/{*path}", get(panel))
807        .route("/fonts/{*path}", get(panel))
808        .route("/favicon.svg", get(panel))
809        // gin reads management bodies without a size limit (uploads, config writes);
810        // they are only read after authentication.
811        .layer(DefaultBodyLimit::disable())
812        .layer(middleware::from_fn_with_state(state.rt.clone(), cors))
813        .with_state(state)
814}
815
816pub(crate) async fn config(
817    State(state): State<Arc<Management>>,
818    OriginalUri(uri): OriginalUri,
819    method: Method,
820    headers: HeaderMap,
821    body: axum::body::Body,
822) -> Response {
823    // gin's *path parameter is the decoded path.
824    let path = percent_decode(uri.path());
825    let if_match: Vec<_> = headers
826        .get_all(header::IF_MATCH)
827        .iter()
828        .map(|v| String::from_utf8_lossy(v.as_bytes()).into_owned())
829        .collect();
830    // Go reads the body only for writes other than DELETE, under its lock, after the file
831    // read, the If-Match check and the stored config's parse. Those run here under the
832    // disk lock, which is released while the body arrives, and again under it before
833    // the write.
834    let body = if matches!(method, Method::GET | Method::DELETE) {
835        Ok(Bytes::new())
836    } else {
837        let check = {
838            let (state, method, if_match) = (state.clone(), method.clone(), if_match.clone());
839            tokio::task::spawn_blocking(move || {
840                let _guard = state.disk.lock().unwrap_or_else(PoisonError::into_inner);
841                stored(&state, &method, &if_match).err()
842            })
843        };
844        match check.await {
845            Ok(Some(response)) => return *response,
846            Ok(None) => {}
847            Err(_) => return error(500, "internal_error"),
848        }
849        axum::body::to_bytes(body, usize::MAX).await.map_err(|e| {
850            if crate::body_limit::is_too_large(&e) {
851                StatusCode::PAYLOAD_TOO_LARGE
852            } else {
853                StatusCode::BAD_REQUEST
854            }
855        })
856    };
857    tokio::task::spawn_blocking(move || config_sync(&state, &path, method, &if_match, body.as_deref().map_err(|s| *s)))
858        .await
859        .unwrap_or_else(|_| error(500, "internal_error"))
860}
861
862pub(crate) fn percent_decode(path: &str) -> String {
863    let bytes = path.as_bytes();
864    let mut out = Vec::with_capacity(bytes.len());
865    let mut i = 0;
866    while i < bytes.len() {
867        let hex = bytes
868            .get(i + 1..i + 3)
869            .and_then(|h| u8::from_str_radix(std::str::from_utf8(h).ok()?, 16).ok());
870        match (bytes[i], hex) {
871            (b'%', Some(b)) => {
872                out.push(b);
873                i += 3;
874            }
875            (b, _) => {
876                out.push(b);
877                i += 1;
878            }
879        }
880    }
881    String::from_utf8_lossy(&out).into_owned()
882}
883
884/// Root-level comment lines after the last mapping entry.
885fn foot_comments(text: &str) -> String {
886    let lines: Vec<&str> = text.lines().collect();
887    let last = lines
888        .iter()
889        .rposition(|l| !l.trim().is_empty() && !l.starts_with('#'))
890        .map_or(0, |i| i + 1);
891    lines[last..]
892        .iter()
893        .filter(|l| l.starts_with('#'))
894        .map(|l| format!("{l}\n"))
895        .collect()
896}
897
898fn invalid_config(status: StatusCode, err: impl std::fmt::Display) -> Response {
899    json(status, &json!({"error": "invalid_config", "message": err.to_string()}))
900}
901
902/// Stores the bcrypt hash of a plaintext management key at `path`. `decoded` is the
903/// key as the config decodes it, so a number or bool written there (`123`) is hashed as
904/// its string, as Go's `ParseConfigBytes` does before publishing.
905fn hash_secret(doc: &mut ConfigDocument, path: &[&str], decoded: &str) -> Option<Response> {
906    if decoded.is_empty() || is_bcrypt(decoded) {
907        return None;
908    }
909    match bcrypt::hash(decoded, bcrypt::DEFAULT_COST) {
910        Err(e) => Some(invalid_config(StatusCode::UNPROCESSABLE_ENTITY, e)),
911        Ok(hash) => doc
912            .update(path, hash.into(), false)
913            .err()
914            .map(|_| error(422, "invalid_config")),
915    }
916}
917
918/// Go `Handler.ConfigV8`: every call reads the file and migrates it in memory (legacy
919/// layout to v8, unknown sections archived as comments); only successful mutations
920/// persist. The write keeps untouched text byte-stable instead of Go's re-encoding.
921///
922/// Reads carry an `ETag` with the SHA-256 of the file bytes; a write with `If-Match`
923/// lines that do not name the current version fails with 412 (v8.0.35 `fa68946a`).
924pub(crate) fn config_sync(
925    state: &Management,
926    path: &str,
927    method: Method,
928    if_match: &[String],
929    body: Result<&[u8], StatusCode>,
930) -> Response {
931    let _guard = state.disk.lock().unwrap_or_else(PoisonError::into_inner);
932    config_sync_locked(state, path, method, if_match, body, false)
933}
934
935/// The stored config as Go's `ConfigV8` prepares it before reading a body: the file
936/// bytes and their `ETag`, the `If-Match` check for writes, then the parsed document.
937/// Errors are Go's answers. Call it holding `state.disk`.
938fn stored(
939    state: &Management,
940    method: &Method,
941    if_match: &[String],
942) -> Result<(String, HeaderValue, ConfigDocument), Box<Response>> {
943    let raw = std::fs::read(&state.path).map_err(|_| Box::new(error(500, "read_failed")))?;
944    let etag = config_etag(&raw);
945    if method != Method::GET && !if_match_satisfied(if_match, &etag) {
946        let mut response = error(412, "precondition_failed");
947        response.headers_mut().insert(header::ETAG, etag);
948        return Err(Box::new(response));
949    }
950    let invalid = |e: &dyn std::fmt::Display| Box::new(invalid_config(StatusCode::INTERNAL_SERVER_ERROR, e));
951    let original = String::from_utf8(raw).map_err(|_| invalid(&"yaml: invalid leading UTF-8 octet"))?;
952    let doc = ConfigDocument::parse(&original).map_err(|e| invalid(&e))?;
953    Ok((original, etag, doc))
954}
955
956/// [`config_sync`] for a caller already holding `state.disk`. `typed` saves the written
957/// values as Go's typed v0 saver does (`SaveConfigPreserveComments`); a v8 write saves
958/// the validated tree as written (Go v8.0.35).
959fn config_sync_locked(
960    state: &Management,
961    path: &str,
962    method: Method,
963    if_match: &[String],
964    body: Result<&[u8], StatusCode>,
965    typed: bool,
966) -> Response {
967    let (original, etag, mut doc) = match stored(state, &method, if_match) {
968        Ok(v) => v,
969        Err(response) => return *response,
970    };
971    let basis = doc.migrated_text(&original).unwrap_or_else(|| original.clone());
972    let archived = doc.archive_unknown();
973    // Go keys this on the matched route: `/config/config.yaml` is a key lookup.
974    let yaml = matches!(path, "/v8/management/config.yaml" | "/v0/management/config.yaml");
975    let suffix = path
976        .strip_prefix("/v8/management/config/")
977        .unwrap_or_default()
978        .trim_matches('/');
979    let parts: Vec<_> = if suffix.is_empty() {
980        vec![]
981    } else {
982        suffix.split('/').collect()
983    };
984    if method == Method::GET {
985        // Go v8.0.35 (3be5fa44): a historical path reads the canonical values, with
986        // the file's YAML types. Cost: a GET parses the file twice, for the write
987        // document (`stored`) and for this view.
988        let mut view = match ConfigDocument::view(&original) {
989            Ok(view) => view,
990            Err(e) => return invalid_config(StatusCode::INTERNAL_SERVER_ERROR, e),
991        };
992        view.archive_unknown();
993        view.project_aliases(&parts);
994        if yaml {
995            return match doc.render_preserving(&basis) {
996                Ok(text) => (
997                    [
998                        (
999                            header::CONTENT_TYPE,
1000                            HeaderValue::from_static("application/yaml; charset=utf-8"),
1001                        ),
1002                        (header::CACHE_CONTROL, HeaderValue::from_static("no-store")),
1003                        (header::ETAG, etag),
1004                    ],
1005                    text + &archive_comments(&archived),
1006                )
1007                    .into_response(),
1008                Err(_) => error(500, "decode_failed"),
1009            };
1010        }
1011        let mut result = match serde_json::to_value(cpa_core::config::AsJson(view.value())) {
1012            Ok(v) => v,
1013            Err(_) => return error(500, "decode_failed"),
1014        };
1015        // Go parses the stored document for this, falling back to the live config.
1016        let cfg = doc.yaml().ok().and_then(|text| Config::parse(&text).ok());
1017        let cfg = cfg.map_or_else(|| state.rt.config(), Arc::new);
1018        auth_index::inject(&mut result, &cfg, &live_auth_indexes(state));
1019        // TURN passwords are omitted from JSON reads, never from YAML downloads.
1020        if let Some(servers) = result
1021            .pointer_mut("/oauth/providers/codex/live-media-relay/ice-servers")
1022            .and_then(Value::as_array_mut)
1023        {
1024            for server in servers {
1025                if let Some(map) = server.as_object_mut() {
1026                    map.remove("username");
1027                    map.remove("credential");
1028                }
1029            }
1030        }
1031        let mut selected = &result;
1032        for part in &parts {
1033            let Some(next) = selected.as_object().and_then(|o| o.get(*part)) else {
1034                return error(404, "not_found");
1035            };
1036            selected = next;
1037        }
1038        let mut response = json(StatusCode::OK, selected);
1039        let headers = response.headers_mut();
1040        headers.insert(header::CACHE_CONTROL, HeaderValue::from_static("no-store"));
1041        headers.insert(header::ETAG, etag);
1042        return response;
1043    }
1044    let before = doc.clone();
1045    // A write to a historical path replaces or deletes the canonical values there.
1046    doc.project_aliases(&parts);
1047    let mut written = None;
1048    if method == Method::DELETE {
1049        if parts.is_empty() {
1050            return error(400, "cannot_delete_config");
1051        }
1052        if !doc.delete(&parts) {
1053            return error(404, "not_found");
1054        }
1055    } else {
1056        let body = match body {
1057            Ok(body) => body,
1058            Err(status) => return error(status.as_u16(), "invalid_body"),
1059        };
1060        if !yaml && serde_json::from_slice::<serde::de::IgnoredAny>(body).is_err() {
1061            return error(400, "invalid_json");
1062        }
1063        // yaml.v3 yields no document for an empty or comment-only body (an explicit
1064        // `null` is a document).
1065        let has_document = String::from_utf8_lossy(body).lines().any(|l| {
1066            let t = l.trim();
1067            !t.is_empty() && !t.starts_with('#') && t != "---" && t != "..."
1068        });
1069        let parsed = std::str::from_utf8(body)
1070            .map_err(|_| ())
1071            .and_then(|t| cpa_core::config::parse_yaml(t).map_err(drop));
1072        let mut value = match parsed {
1073            Ok(v) if has_document => v,
1074            _ => return error(400, "invalid_body"),
1075        };
1076        if parts.is_empty() && !value.is_mapping() {
1077            return error(400, "config_must_be_object");
1078        }
1079        // Go keeps a `!!binary` node tagged through the update, after the root shape
1080        // check; decoding it for the save fails on invalid base64 with an invalid
1081        // config (400). A string setting written as a plain number keeps its text, as
1082        // the write document holds it ([`ConfigDocument::parse`]).
1083        if yaml {
1084            value = match std::str::from_utf8(body)
1085                .map_err(anyhow::Error::from)
1086                .and_then(cpa_core::config::config_value)
1087            {
1088                Ok(v) => v,
1089                Err(e) => return invalid_config(StatusCode::BAD_REQUEST, e),
1090            };
1091        } else if let Ok(v) = std::str::from_utf8(body)
1092            .map_err(anyhow::Error::from)
1093            .and_then(|text| cpa_core::config::body_value(text, &parts))
1094        {
1095            // A JSON number in a string setting saves as Go saves its node: its text.
1096            value = v;
1097        }
1098        // A YAML upload is alias-normalized first, where a scalar merge fails (Go
1099        // `NormalizeV8ConfigAliases`, 400). JSON keys are quoted, so Go keeps `<<` as a
1100        // plain key through the update and expands it only when it parses its own save,
1101        // which writes it plain: below.
1102        if yaml && let Err(e) = cpa_core::config::expand_merges(&mut value) {
1103            return invalid_config(StatusCode::BAD_REQUEST, e);
1104        }
1105        auth_index::strip_update(&parts, &mut value);
1106        if parts.is_empty() {
1107            ConfigDocument::normalize_aliases(&mut value);
1108        }
1109        if doc.update(&parts, value.clone(), method == Method::PATCH).is_err() {
1110            return error(400, "invalid_path");
1111        }
1112        if !yaml {
1113            doc.preserve_turn_secrets(&before);
1114        }
1115        written = Some(value);
1116        // The completed candidate, as Go reparses it: keys already there win over merged
1117        // ones, and a scalar merge is an invalid config (422).
1118        if !yaml && let Err(e) = cpa_core::config::expand_merges(doc.value_mut()) {
1119            return invalid_config(StatusCode::UNPROCESSABLE_ENTITY, e);
1120        }
1121    }
1122    ConfigDocument::normalize_aliases(doc.value_mut());
1123    // Go saves every v8 write as `NormalizeConfigLayout` output, which declares the
1124    // version even when a whole-config PUT omitted it.
1125    if let Some(root) = doc.value_mut().as_mapping_mut()
1126        && !root.contains_key("config-version")
1127    {
1128        root.insert("config-version".into(), 8.into());
1129    }
1130    auth_index::strip_root(doc.value_mut());
1131    for field in [
1132        "credentials/concurrency/lifecycle-config-revision",
1133        "credentials/concurrency/observation-barrier-revision",
1134        "plugins/auth-revision",
1135    ] {
1136        let parts: Vec<_> = field.split('/').collect();
1137        if doc.get(&parts) != before.get(&parts) {
1138            return json(
1139                StatusCode::BAD_REQUEST,
1140                &json!({"error": "read_only_field", "field": field}),
1141            );
1142        }
1143    }
1144    let text = match doc.yaml() {
1145        Ok(v) => v,
1146        Err(e) => return invalid_config(StatusCode::BAD_REQUEST, e),
1147    };
1148    // Go `ParseConfigBytes` (422), which checks the layout shape, the key groups and
1149    // the weights unwrapped before it decodes, then `ValidateV8Config` (400) the layout
1150    // before its strict decode.
1151    let parsed = match Config::parse_payload(&text) {
1152        Ok(v) => v,
1153        Err(e) => return invalid_config(StatusCode::UNPROCESSABLE_ENTITY, e),
1154    };
1155    if let Some(e) = cpa_core::config::v8_layout_error(doc.value()) {
1156        return invalid_config(StatusCode::BAD_REQUEST, e);
1157    }
1158    if let Err(e) = cpa_core::config::validate_config_fields(doc.value(), true) {
1159        return invalid_config(StatusCode::BAD_REQUEST, e);
1160    }
1161    // Go's v0 saver persists typed values; projecting only after validation keeps
1162    // malformed input from being sanitized into success.
1163    if typed && let Some(written) = &written {
1164        doc.typed_projection(&parts, written, method == Method::PATCH);
1165    }
1166    if let Some(response) = hash_secret(&mut doc, &["management", "secret-key"], &parsed.management.secret_key) {
1167        return response;
1168    }
1169    let basis = if yaml {
1170        match std::str::from_utf8(body.unwrap_or_default()) {
1171            Ok(v) => v.to_owned(),
1172            Err(_) => return error(400, "invalid_body"),
1173        }
1174    } else {
1175        basis
1176    };
1177    let mut text = match doc.render_preserving(&basis) {
1178        Ok(v) => v,
1179        Err(e) => return invalid_config(StatusCode::INTERNAL_SERVER_ERROR, e),
1180    };
1181    // Go keeps document-level foot comments (its archive of unknown sections) even
1182    // when the root mapping is replaced by a YAML upload.
1183    if yaml {
1184        text += &foot_comments(&original);
1185    }
1186    text += &archive_comments(&archived);
1187    let cfg = match Config::parse_payload(&text) {
1188        Ok(v) => v,
1189        Err(e) => return invalid_config(StatusCode::UNPROCESSABLE_ENTITY, e),
1190    };
1191    if let Err(e) = ConfigDocument::write(&state.path, &text) {
1192        return json(
1193            StatusCode::INTERNAL_SERVER_ERROR,
1194            &json!({"error": "write_failed", "message": e.to_string()}),
1195        );
1196    }
1197    state.publish(cfg, None);
1198    let mut response = json(StatusCode::OK, &json!({"config-version": 8, "status": "ok"}));
1199    // The version actually on disk; none when it cannot be read back.
1200    if let Ok(saved) = std::fs::read(&state.path) {
1201        response.headers_mut().insert(header::ETAG, config_etag(&saved));
1202    }
1203    response
1204}
1205
1206/// What a v0 save does at its legacy path.
1207pub(crate) enum LegacyEdit {
1208    Set(serde_json::Value),
1209    Delete,
1210    /// Rewrite unchanged, as Go saves after a handler that changed nothing.
1211    Keep,
1212}
1213
1214/// A v0 save at the v8 path: `Some(value)` replaces it, `None` deletes it.
1215pub(crate) struct V8Edit<'a> {
1216    pub path: &'a str,
1217    pub value: Option<Value>,
1218}
1219
1220/// Test hook run once by the next [`Management::publish`] for the auth folder it names,
1221/// after it has built its fallback credentials and before it reconciles them.
1222#[cfg(test)]
1223pub(crate) static BEFORE_RECONCILE: Mutex<Vec<(PathBuf, LayoutHook)>> = Mutex::new(Vec::new());
1224
1225/// Test hook run once, for the config file it names, when [`v0_save`] has chosen the v8
1226/// writer and not yet written: the boundary where an unlocked save would let another
1227/// writer in.
1228#[cfg(test)]
1229pub(crate) static AFTER_LAYOUT: Mutex<Option<(PathBuf, LayoutHook)>> = Mutex::new(None);
1230#[cfg(test)]
1231pub(crate) type LayoutHook = Box<dyn FnOnce() + Send>;
1232
1233/// Go v8.0.35 `SaveConfigPreserveComments`: a v0 save keeps a file without v8 sections
1234/// in its legacy layout, so legacy settings keep their scope (a legacy
1235/// `codex-header-defaults` still applies to API keys); a v8 file saves through the v8
1236/// writer. The caller holds the `disk` lock across the layout check and the chosen
1237/// write, so an upload cannot change the layout in between, and across reading the
1238/// value it changes, so a concurrent save cannot be lost (Go 1631875b).
1239/// ponytail: the legacy branch changes only the edited key; Go also merges its whole
1240/// typed legacy render into the file and drops removed integration keys. Port
1241/// `mergeMappingPreserve` here if a difference in the saved file matters.
1242pub(crate) fn v0_save(
1243    state: &Management,
1244    _disk: &std::sync::MutexGuard<'_, ()>,
1245    legacy: &[&str],
1246    edit: LegacyEdit,
1247    v8: V8Edit,
1248) -> Response {
1249    let original = match std::fs::read_to_string(&state.path) {
1250        Ok(v) => v,
1251        Err(_) => return error(500, "read_failed"),
1252    };
1253    // Go's saver works on the alias- and merge-expanded root mapping (`flattenV8`).
1254    let mut root = match cpa_core::config::config_value(&original) {
1255        Ok(v) => v,
1256        Err(e) => return invalid_config(StatusCode::INTERNAL_SERVER_ERROR, e),
1257    };
1258    if let Err(e) = cpa_core::config::expand_merges(&mut root) {
1259        return invalid_config(StatusCode::INTERNAL_SERVER_ERROR, e);
1260    }
1261    if !root.is_mapping() {
1262        return invalid_config(StatusCode::INTERNAL_SERVER_ERROR, "expected root mapping node");
1263    }
1264    if cpa_core::config::is_v8_layout(&root) {
1265        #[cfg(test)]
1266        {
1267            let hook = {
1268                let mut slot = AFTER_LAYOUT.lock().unwrap_or_else(PoisonError::into_inner);
1269                match slot.as_ref() {
1270                    Some((path, _)) if *path == state.path => slot.take(),
1271                    _ => None,
1272                }
1273            };
1274            if let Some((_, hook)) = hook {
1275                hook();
1276            }
1277        }
1278        return match v8.value {
1279            Some(value) => config_sync_locked(state, v8.path, Method::PUT, &[], Ok(value.to_string().as_bytes()), true),
1280            None => config_sync_locked(state, v8.path, Method::DELETE, &[], Ok(b""), true),
1281        };
1282    }
1283    let mut doc = ConfigDocument::unmigrated(root);
1284    match edit {
1285        LegacyEdit::Set(value) => {
1286            let value = match serde_yaml_ng::to_value(value) {
1287                Ok(v) => v,
1288                Err(e) => return invalid_config(StatusCode::BAD_REQUEST, e),
1289            };
1290            if doc.update(legacy, value, false).is_err() {
1291                return error(400, "invalid_path");
1292            }
1293        }
1294        LegacyEdit::Delete => {
1295            doc.delete(legacy);
1296        }
1297        LegacyEdit::Keep => {}
1298    }
1299    // Go saves its in-memory config, whose key is hashed on load; a plaintext key
1300    // edited into the file since must not be published.
1301    let parsed = match doc.yaml().and_then(|t| Config::parse(&t)) {
1302        Ok(v) => v,
1303        Err(e) => return invalid_config(StatusCode::UNPROCESSABLE_ENTITY, e),
1304    };
1305    if let Some(response) = hash_secret(
1306        &mut doc,
1307        &["remote-management", "secret-key"],
1308        &parsed.management.secret_key,
1309    ) {
1310        return response;
1311    }
1312    let text = match doc.render_preserving(&original) {
1313        Ok(v) => v,
1314        Err(e) => return invalid_config(StatusCode::INTERNAL_SERVER_ERROR, e),
1315    };
1316    let cfg = match Config::parse(&text) {
1317        Ok(v) => v,
1318        Err(e) => return invalid_config(StatusCode::UNPROCESSABLE_ENTITY, e),
1319    };
1320    if let Err(e) = ConfigDocument::write(&state.path, &text) {
1321        return json(
1322            StatusCode::INTERNAL_SERVER_ERROR,
1323            &json!({"error": "write_failed", "message": e.to_string()}),
1324        );
1325    }
1326    state.publish(cfg, None);
1327    json(StatusCode::OK, &json!({"status": "ok"}))
1328}
1329
1330/// Go `liveAuthIndexFromManager`: the index each config-backed credential carries.
1331fn live_auth_indexes(state: &Management) -> std::collections::HashMap<String, String> {
1332    state
1333        .rt
1334        .store()
1335        .snapshot()
1336        .iter()
1337        .filter(|c| matches!(c.source, Source::Config { .. }))
1338        .map(|c| (c.id.clone(), credentials::auth_index(c)))
1339        .collect()
1340}
1341
1342/// Go `configV8ETag(ComputeSourceHash(raw))`: a strong tag of the file's SHA-256.
1343fn config_etag(raw: &[u8]) -> HeaderValue {
1344    use sha2::{Digest, Sha256};
1345    let hex: String = Sha256::digest(raw).iter().map(|b| format!("{b:02x}")).collect();
1346    HeaderValue::try_from(format!("\"{hex}\"")).expect("hex is a valid header value")
1347}
1348
1349/// Go `ifMatchSatisfied`: RFC 9110 strong comparison over every `If-Match` line as one
1350/// list. Absent passes, blank fails, a whole-field `*` matches any version, and weak
1351/// or malformed tags never match. A comma inside a quoted tag is not a separator.
1352fn if_match_satisfied(values: &[String], etag: &HeaderValue) -> bool {
1353    if values.is_empty() {
1354        return true;
1355    }
1356    // `strings.TrimSpace`: Unicode white space too.
1357    let trim = |s: &[u8]| cpa_common::gostr::trim_space(s).to_vec();
1358    let field = trim(values.join(",").as_bytes());
1359    if field == b"*" {
1360        return true;
1361    }
1362    let mut quoted = false;
1363    field
1364        .split(|&c| {
1365            quoted ^= c == b'"';
1366            c == b',' && !quoted
1367        })
1368        .any(|tag| trim(tag) == etag.as_bytes())
1369}
1370
1371async fn legacy_yaml(State(state): State<Arc<Management>>) -> Response {
1372    match tokio::fs::read(&state.path).await {
1373        Ok(bytes) => ([(header::CONTENT_TYPE, "application/yaml; charset=utf-8")], bytes).into_response(),
1374        Err(_) => error(404, "not_found"),
1375    }
1376}
1377
1378include!(concat!(env!("OUT_DIR"), "/dashboard.rs"));
1379
1380async fn panel(State(state): State<Arc<Management>>, OriginalUri(uri): OriginalUri) -> Response {
1381    if state.rt.config().management.disable_control_panel {
1382        return error(404, "not_found");
1383    }
1384    let Some((bytes, mime)) = dashboard_asset(uri.path()) else {
1385        return error(404, "not_found");
1386    };
1387    (
1388        [(header::CONTENT_TYPE, mime), (header::CACHE_CONTROL, "no-cache")],
1389        bytes,
1390    )
1391        .into_response()
1392}