akanjs 3.0.0-beta.20 → 3.0.0-beta.21

package/vendor/@akanjs/native/native/desktop/src/linux/dock.rs

@@ -0,0 +1,146 @@
+//! The dock plugin (and the badge plugin's count) on Linux, with the ops and state of dock.rs:
+//!   dock.setBadge    → the launcher entry's count: com.canonical.Unity.LauncherEntry
+//!   dock.setProgress → its progress bar (paused and error draw like normal)
+//!   dock.setVisible  → the windows' skip-taskbar and skip-pager hints
+//!   dock.getState
+//!
+//! The LauncherEntry API is a D-Bus signal, Update(s app_uri, a{sv} properties), which docks and
+//! task managers that support it (Ubuntu's dock, Dash to Dock, KDE Plasma's task manager) match to
+//! the app's desktop entry. tao reaches it through libunity with dlopen and only while Unity itself
+//! runs (tao-0.37.0/src/platform_impl/linux/taskbar.rs:52-97); here GDBus emits the signal on the
+//! session bus directly, and the object also answers Query() for a dock that starts later. Tauri
+//! names the entry "<package>.desktop" (tauri/crates/tauri/src/window/mod.rs:2406-2440); akan-native uses
+//! the app id, "application://<app id>.desktop", so the app's desktop file must be named so.
+//! Without such a desktop entry (a plain `akan-native run`), nothing shows, but the state is kept.
+//!
+//! A launcher shows a count, not text: labels other than a whole number are UNSUPPORTED.
+
+use std::cell::RefCell;
+
+use gtk::{
+  gio,
+  glib::{self, ToVariant, Variant},
+  prelude::*,
+};
+
+use crate::{
+  chrome::{self, Progress},
+  json::V,
+};
+
+const PATH: &str = "/com/canonical/unity/launcherentry/akan_native";
+const INTERFACE: &str = "com.canonical.Unity.LauncherEntry";
+const XML: &str = r#"<node><interface name="com.canonical.Unity.LauncherEntry">
+<method name="Query"><arg type="s" name="app_uri" direction="out"/><arg type="a{sv}" name="properties" direction="out"/></method>
+<signal name="Update"><arg type="s" name="app_uri"/><arg type="a{sv}" name="properties"/></signal>
+</interface></node>"#;
+
+#[derive(Default)]
+struct State {
+  badge: Option<String>,
+  progress: Option<Progress>,
+  hidden: bool,
+  app_uri: String,
+  conn: Option<gio::DBusConnection>,
+}
+
+thread_local! {
+  static STATE: RefCell<State> = RefCell::new(State::default());
+}
+
+fn properties(state: &State) -> Variant {
+  let dict = glib::VariantDict::new(None);
+  let count = state.badge.as_deref().and_then(|b| b.parse::<i64>().ok());
+  dict.insert_value("count", &count.unwrap_or(0).to_variant());
+  dict.insert_value("count-visible", &count.is_some().to_variant());
+  dict.insert_value("progress", &state.progress.map_or(0.0, |p| p.value).to_variant());
+  dict.insert_value("progress-visible", &state.progress.is_some().to_variant());
+  dict.end()
+}
+
+/// The session bus, with the launcher entry object exported once.
+fn connection(state: &mut State) -> Result<gio::DBusConnection, String> {
+  if let Some(conn) = &state.conn {
+    return Ok(conn.clone());
+  }
+  let conn = gio::bus_get_sync(gio::BusType::Session, None::<&gio::Cancellable>).map_err(|e| format!("UNSUPPORTED: no D-Bus session bus for the launcher entry: {e}"))?;
+  let info = gio::DBusNodeInfo::for_xml(XML).ok().and_then(|n| n.lookup_interface(INTERFACE)).expect("valid introspection XML");
+  let registered = conn.register_object(
+    PATH,
+    &info,
+    |_, _, _, _, _, _, invocation| {
+      let reply = STATE.with(|s| {
+        let state = s.borrow();
+        Variant::tuple_from_iter([state.app_uri.to_variant(), properties(&state)])
+      });
+      invocation.return_value(Some(&reply));
+    },
+    |_, _, _, _, _| "".to_variant(),
+    |_, _, _, _, _, _| false,
+  );
+  if let Err(e) = registered {
+    log!("launcher entry: {e}"); // the signal works without the object
+  }
+  state.conn = Some(conn.clone());
+  Ok(conn)
+}
+
+fn update(state: &mut State) -> Result<(), String> {
+  let conn = connection(state)?;
+  let args = Variant::tuple_from_iter([state.app_uri.to_variant(), properties(state)]);
+  conn.emit_signal(None, PATH, INTERFACE, "Update", Some(&args)).map_err(|e| format!("INTERNAL: launcher entry: {e}"))
+}
+
+/// A new window gets the app's taskbar hint (lib.rs open_window → menu.rs window_opened).
+pub fn window_opened(window: &gtk::ApplicationWindow) {
+  if STATE.with(|s| s.borrow().hidden) {
+    hide(window, true);
+  }
+}
+
+fn hide(window: &gtk::ApplicationWindow, hidden: bool) {
+  window.set_skip_taskbar_hint(hidden);
+  window.set_skip_pager_hint(hidden);
+}
+
+fn state_json(state: &State) -> String {
+  chrome::dock_state_json(state.badge.as_deref(), !state.hidden, state.progress)
+}
+
+/// dock.* shell ops; None for other ops.
+pub fn shell_op(op: &str, cmd: &V, app_id: &str) -> Option<Result<String, String>> {
+  if !op.starts_with("dock.") {
+    return None;
+  }
+  Some(STATE.with(|s| {
+    let mut state = s.borrow_mut();
+    // Without an app id (a bare shell), the executable's name.
+    let exe = || std::env::current_exe().ok().and_then(|p| p.file_stem().map(|s| s.to_string_lossy().into_owned())).unwrap_or_default();
+    state.app_uri = format!("application://{}.desktop", if app_id.is_empty() { exe() } else { app_id.to_string() });
+    match op {
+      "dock.getState" => {}
+      "dock.setBadge" => {
+        let label = chrome::parse_label(cmd)?;
+        if let Some(text) = &label {
+          if text.parse::<i64>().map_or(true, |n| n < 0) {
+            return Err(format!("UNSUPPORTED: Linux launchers show a count; {text:?} is not a whole number"));
+          }
+        }
+        state.badge = label;
+        update(&mut state)?;
+      }
+      "dock.setProgress" => {
+        state.progress = chrome::parse_progress(cmd)?;
+        update(&mut state)?;
+      }
+      "dock.setVisible" => {
+        state.hidden = !chrome::parse_visible(cmd)?;
+        for (_, window) in super::menu::gtk_windows() {
+          hide(&window, state.hidden);
+        }
+      }
+      _ => return Err(format!("unknown op {op}")),
+    }
+    Ok(state_json(&state))
+  }))
+}

package/vendor/@akanjs/native/native/desktop/src/linux/hotkey.rs

@@ -0,0 +1,228 @@
+//! Global shortcuts on Linux (global-shortcut plugin, plugins.md §5): XGrabKey on the X root
+//! window, with the ops and events of hotkey.rs. libX11 and GDK's X11 calls are declared here
+//! (no crate); the display is GDK's own, so key presses arrive through GDK's event source on the
+//! main thread, like every other event.
+//!
+//! Know-how from the references:
+//! - Electrobun grabs every combination four times, plain and with NumLock (Mod2) and CapsLock
+//!   (Lock), since X matches the modifier state exactly (electrobun/package/src/native/linux/
+//!   nativeWrapper.cpp:11910-11922; tao's old implementation did the same, tao/CHANGELOG.md:641-646).
+//!   It opens a second display on a polling thread and never sees a failed grab (:11917-11925);
+//!   here GDK's error trap around XSync reports BadAccess, a combination another client holds,
+//!   and a GDK filter on the root window takes the key events (the way the keybinder library does).
+//! - owner_events False: the press is always reported on the root window, also when one of the
+//!   app's own windows has the focus.
+//! - GDK turns on detectable auto-repeat, so a held key sends presses without releases: only the
+//!   first press of a hold is reported, as with MOD_NOREPEAT on Windows.
+//! - Wayland has no global grabs. GNOME and KDE offer shortcuts there only through the
+//!   GlobalShortcuts portal, which asks the user to approve every binding: UNSUPPORTED for now.
+//!
+//! Keys are keysyms turned into the current layout's key codes (accelerator.rs keysym).
+
+use std::{
+  cell::RefCell,
+  ffi::{c_int, c_uchar, c_uint, c_ulong, c_void},
+};
+
+use gtk::{gdk, glib::translate::ToGlibPtr, prelude::*};
+
+use crate::{accelerator, json, push_event};
+
+type XDisplay = c_void;
+
+/// XKeyEvent (X11/Xlib.h); KeyPress and KeyRelease share it.
+#[repr(C)]
+struct XKeyEvent {
+  kind: c_int,
+  serial: c_ulong,
+  send_event: c_int,
+  display: *mut XDisplay,
+  window: c_ulong,
+  root: c_ulong,
+  subwindow: c_ulong,
+  time: c_ulong,
+  x: c_int,
+  y: c_int,
+  x_root: c_int,
+  y_root: c_int,
+  state: c_uint,
+  keycode: c_uint,
+  same_screen: c_int,
+}
+
+#[link(name = "X11")]
+extern "C" {
+  fn XGrabKey(display: *mut XDisplay, keycode: c_int, modifiers: c_uint, grab_window: c_ulong, owner_events: c_int, pointer_mode: c_int, keyboard_mode: c_int) -> c_int;
+  fn XUngrabKey(display: *mut XDisplay, keycode: c_int, modifiers: c_uint, grab_window: c_ulong) -> c_int;
+  fn XKeysymToKeycode(display: *mut XDisplay, keysym: c_ulong) -> c_uchar;
+  fn XDefaultRootWindow(display: *mut XDisplay) -> c_ulong;
+  fn XSync(display: *mut XDisplay, discard: c_int) -> c_int;
+}
+
+#[link(name = "gdk-3")]
+extern "C" {
+  fn gdk_x11_display_get_xdisplay(display: *mut gdk::ffi::GdkDisplay) -> *mut XDisplay;
+  fn gdk_x11_display_error_trap_push(display: *mut gdk::ffi::GdkDisplay);
+  fn gdk_x11_display_error_trap_pop(display: *mut gdk::ffi::GdkDisplay) -> c_int;
+}
+
+const KEY_PRESS: c_int = 2;
+const KEY_RELEASE: c_int = 3;
+const GRAB_MODE_ASYNC: c_int = 1;
+const BAD_ACCESS: c_int = 10;
+const LOCK_MASK: c_uint = 1 << 1;
+const MOD2_MASK: c_uint = 1 << 4; // NumLock on nearly every keyboard map
+/// The modifiers a shortcut is made of (accelerator.rs x11_modifiers).
+const MODIFIERS: c_uint = 1 | 4 | 8 | 64;
+const IGNORED: [c_uint; 4] = [0, LOCK_MASK, MOD2_MASK, LOCK_MASK | MOD2_MASK];
+
+struct Entry {
+  /// X key code and modifier state.
+  combo: (c_uint, c_uint),
+  /// As the page wrote it; `pressed` reports this.
+  accelerator: String,
+  /// Down now (auto-repeat sends more presses).
+  down: bool,
+}
+
+thread_local! {
+  static HOTKEYS: RefCell<Vec<Entry>> = const { RefCell::new(Vec::new()) };
+  static FILTER: std::cell::Cell<bool> = const { std::cell::Cell::new(false) };
+}
+
+/// GDK's X display, or why there is none.
+fn x11() -> Result<(gdk::Display, *mut XDisplay), String> {
+  let display = gdk::Display::default().ok_or("there is no display")?;
+  if display.type_().name() != "GdkX11Display" {
+    return Err("UNSUPPORTED: global shortcuts need X11; Wayland offers them only through the GlobalShortcuts portal, which akan-native does not use yet".into());
+  }
+  let xdisplay = unsafe { gdk_x11_display_get_xdisplay(display.to_glib_none().0) };
+  Ok((display, xdisplay))
+}
+
+unsafe extern "C" fn filter(xevent: *mut gdk::ffi::GdkXEvent, _event: *mut gdk::ffi::GdkEvent, _data: *mut c_void) -> gdk::ffi::GdkFilterReturn {
+  let key = &*(xevent as *const XKeyEvent);
+  if key.kind != KEY_PRESS && key.kind != KEY_RELEASE {
+    return gdk::ffi::GDK_FILTER_CONTINUE;
+  }
+  let combo = (key.keycode, key.state & MODIFIERS);
+  let pressed = HOTKEYS.with(|h| {
+    let mut hotkeys = h.borrow_mut();
+    let entry = hotkeys.iter_mut().find(|e| e.combo == combo)?;
+    let first = key.kind == KEY_PRESS && !entry.down;
+    entry.down = key.kind == KEY_PRESS;
+    Some(first.then(|| entry.accelerator.clone()))
+  });
+  match pressed {
+    None => gdk::ffi::GDK_FILTER_CONTINUE,
+    Some(accelerator) => {
+      if let Some(accelerator) = accelerator {
+        push_event(&format!(r#"{{"type":"hotkey","accelerator":{}}}"#, json::quote(&accelerator)));
+      }
+      gdk::ffi::GDK_FILTER_REMOVE
+    }
+  }
+}
+
+fn ensure_filter(display: &gdk::Display) {
+  if FILTER.with(|f| f.replace(true)) {
+    return;
+  }
+  let root = display.default_screen().root_window();
+  unsafe { gdk::ffi::gdk_window_add_filter(root.to_glib_none().0, Some(filter), std::ptr::null_mut()) };
+}
+
+fn combo(text: &str, xdisplay: *mut XDisplay) -> Result<(accelerator::Accelerator, (c_uint, c_uint)), String> {
+  let accel = accelerator::parse(text)?;
+  let keysym = accel.keysym().ok_or_else(|| format!("{text} has no key on Linux"))?;
+  let code = unsafe { XKeysymToKeycode(xdisplay, keysym as c_ulong) };
+  if code == 0 {
+    return Err(format!("{text}: the keyboard layout has no such key"));
+  }
+  Ok((accel.clone(), (code as c_uint, accel.x11_modifiers())))
+}
+
+fn grab(display: &gdk::Display, xdisplay: *mut XDisplay, (code, mods): (c_uint, c_uint), on: bool) -> c_int {
+  let gdk_display = display.to_glib_none().0;
+  unsafe {
+    let root = XDefaultRootWindow(xdisplay);
+    gdk_x11_display_error_trap_push(gdk_display);
+    for extra in IGNORED {
+      if on {
+        XGrabKey(xdisplay, code as c_int, mods | extra, root, 0, GRAB_MODE_ASYNC, GRAB_MODE_ASYNC);
+      } else {
+        XUngrabKey(xdisplay, code as c_int, mods | extra, root);
+      }
+    }
+    XSync(xdisplay, 0);
+    gdk_x11_display_error_trap_pop(gdk_display)
+  }
+}
+
+/// Registers a shortcut; one this app already has succeeds. Returns the canonical spelling.
+fn register(text: &str) -> Result<String, String> {
+  let (display, xdisplay) = x11()?;
+  let (accel, combo) = combo(text, xdisplay)?;
+  if HOTKEYS.with(|h| h.borrow().iter().any(|e| e.combo == combo)) {
+    return Ok(accel.canonical());
+  }
+  ensure_filter(&display);
+  match grab(&display, xdisplay, combo, true) {
+    0 => {}
+    error => {
+      grab(&display, xdisplay, combo, false); // the variants that did succeed
+      return Err(if error == BAD_ACCESS { format!("{text} is already taken by another app") } else { format!("cannot register {text} (X error {error})") });
+    }
+  }
+  HOTKEYS.with(|h| h.borrow_mut().push(Entry { combo, accelerator: text.to_string(), down: false }));
+  Ok(accel.canonical())
+}
+
+fn unregister(text: &str) -> Result<bool, String> {
+  let (display, xdisplay) = x11()?;
+  let (_, combo) = combo(text, xdisplay)?;
+  let removed = HOTKEYS.with(|h| {
+    let mut hotkeys = h.borrow_mut();
+    let index = hotkeys.iter().position(|e| e.combo == combo)?;
+    Some(hotkeys.remove(index))
+  });
+  if removed.is_some() {
+    grab(&display, xdisplay, combo, false);
+  }
+  Ok(removed.is_some())
+}
+
+fn unregister_all() -> Result<(), String> {
+  let entries = HOTKEYS.with(|h| std::mem::take(&mut *h.borrow_mut()));
+  if entries.is_empty() {
+    return Ok(());
+  }
+  let (display, xdisplay) = x11()?;
+  for entry in entries {
+    grab(&display, xdisplay, entry.combo, false);
+  }
+  Ok(())
+}
+
+fn is_registered(text: &str) -> Result<bool, String> {
+  let (_, xdisplay) = x11()?;
+  let (_, combo) = combo(text, xdisplay)?;
+  Ok(HOTKEYS.with(|h| h.borrow().iter().any(|e| e.combo == combo)))
+}
+
+fn accelerator_arg(cmd: &json::V) -> Result<&str, String> {
+  cmd.get("accelerator").and_then(|v| v.as_str()).ok_or_else(|| "accelerator must be a string".to_string())
+}
+
+/// hotkey.* shell ops; None for other ops.
+pub fn shell_op(op: &str, cmd: &json::V) -> Option<Result<String, String>> {
+  let result = match op {
+    "hotkey.register" => accelerator_arg(cmd).and_then(register).map(|c| format!(r#"{{"accelerator":{}}}"#, json::quote(&c))),
+    "hotkey.unregister" => accelerator_arg(cmd).and_then(unregister).map(|removed| format!(r#"{{"removed":{removed}}}"#)),
+    "hotkey.unregisterAll" => unregister_all().map(|()| "null".into()),
+    "hotkey.isRegistered" => accelerator_arg(cmd).and_then(is_registered).map(|r| format!(r#"{{"registered":{r}}}"#)),
+    "hotkey.list" => Ok(HOTKEYS.with(|h| format!("[{}]", h.borrow().iter().map(|e| json::quote(&e.accelerator)).collect::<Vec<_>>().join(",")))),
+    _ => return None,
+  };
+  Some(result)
+}

package/vendor/@akanjs/native/native/desktop/src/linux/keychain.rs

@@ -0,0 +1,243 @@
+//! Secrets on Linux: the Secret Service API (org.freedesktop.secrets: gnome-keyring, KWallet 5.97+,
+//! KeePassXC) over the session bus through GDBus from gtk-rs, with the same ops as keychain.rs on
+//! macOS (secure-storage keeps its data key there):
+//!   keychain.get    {service, account}                → {"value": string | null}
+//!   keychain.set    {service, account, value, label?} → null
+//!   keychain.delete {service, account}                → null
+//! An item carries the attributes service and account (what `secret-tool lookup service … account …`
+//! finds) and lives in the "default" collection (the login keyring). Secrets travel over the
+//! "plain" session algorithm: the bus is the user's own, as with libsecret by default.
+//! A locked item or collection is unlocked first; the service may show its password prompt, and
+//! a dismissed prompt is PERMISSION_DENIED. No Secret Service on the bus is UNSUPPORTED.
+
+use std::collections::HashMap;
+use std::sync::{Arc, Mutex};
+use std::time::{Duration, Instant};
+
+use gtk::gio;
+use gtk::glib::{self, variant::ObjectPath, ToVariant, Variant, VariantTy};
+
+use crate::json;
+
+const NAME: &str = "org.freedesktop.secrets";
+const PATH: &str = "/org/freedesktop/secrets";
+const SERVICE: &str = "org.freedesktop.Secret.Service";
+const ITEM: &str = "org.freedesktop.Secret.Item";
+const TIMEOUT_MS: i32 = 10_000;
+/// How long a password prompt may stay open.
+const PROMPT_WAIT: Duration = Duration::from_secs(300);
+
+struct Secrets {
+  conn: gio::DBusConnection,
+  session: ObjectPath,
+}
+
+fn failed(what: &str, e: &glib::Error) -> String {
+  let message = e.message();
+  let name = message.strip_prefix("GDBus.Error:").and_then(|rest| rest.split_once(':')).map(|(name, _)| name);
+  match name {
+    Some("org.freedesktop.DBus.Error.ServiceUnknown") | Some("org.freedesktop.DBus.Error.NameHasNoOwner") => {
+      format!("UNSUPPORTED: this session has no Secret Service ({NAME}, e.g. gnome-keyring): {message}")
+    }
+    Some(n) if n.starts_with("org.freedesktop.DBus.Error.Spawn.") => format!("UNSUPPORTED: the Secret Service did not start: {message}"),
+    _ => format!("INTERNAL: Secret Service {what} failed: {message}"),
+  }
+}
+
+fn path(p: &str) -> Result<ObjectPath, String> {
+  ObjectPath::try_from(p.to_string()).map_err(|_| format!("INTERNAL: not an object path: {p}"))
+}
+
+impl Secrets {
+  fn open() -> Result<Self, String> {
+    let conn = gio::bus_get_sync(gio::BusType::Session, None::<&gio::Cancellable>).map_err(|e| format!("UNSUPPORTED: no D-Bus session bus ({e})"))?;
+    let mut me = Secrets { conn, session: path("/")? };
+    let reply = me.call(PATH, SERVICE, "OpenSession", Some(&("plain", "".to_variant()).to_variant()), "(vo)")?;
+    let (_, session) = reply.get::<(Variant, ObjectPath)>().ok_or("INTERNAL: OpenSession answered no session")?;
+    me.session = session;
+    Ok(me)
+  }
+
+  fn call(&self, object: &str, interface: &str, method: &str, args: Option<&Variant>, reply: &str) -> Result<Variant, String> {
+    let reply = VariantTy::new(reply).expect("a D-Bus reply type");
+    self
+      .conn
+      .call_sync(Some(NAME), object, interface, method, args, Some(reply), gio::DBusCallFlags::NONE, TIMEOUT_MS, None::<&gio::Cancellable>)
+      .map_err(|e| failed(method, &e))
+  }
+
+  /// Runs a prompt the service asked for ("/" = none) and returns its result. The Completed
+  /// signal arrives on this thread's own main context, iterated here until it comes.
+  fn prompt(&self, prompt: &ObjectPath) -> Result<Option<Variant>, String> {
+    if prompt.as_str() == "/" {
+      return Ok(None);
+    }
+    let context = glib::MainContext::new();
+    context
+      .with_thread_default(|| {
+        let done: Arc<Mutex<Option<(bool, Variant)>>> = Arc::new(Mutex::new(None));
+        let sink = done.clone();
+        let subscription = self.conn.signal_subscribe(
+          Some(NAME),
+          Some("org.freedesktop.Secret.Prompt"),
+          Some("Completed"),
+          Some(prompt.as_str()),
+          None,
+          gio::DBusSignalFlags::NONE,
+          move |_, _, _, _, _, params| {
+            if let Some(result) = params.get::<(bool, Variant)>() {
+              *sink.lock().unwrap() = Some(result);
+            }
+          },
+        );
+        // window-id "": no parent window to attach the prompt to.
+        let started = self.call(prompt.as_str(), "org.freedesktop.Secret.Prompt", "Prompt", Some(&("",).to_variant()), "()");
+        let deadline = Instant::now() + PROMPT_WAIT;
+        while started.is_ok() && done.lock().unwrap().is_none() && Instant::now() < deadline {
+          if !context.iteration(false) {
+            std::thread::sleep(Duration::from_millis(20));
+          }
+        }
+        self.conn.signal_unsubscribe(subscription);
+        started?;
+        let result = done.lock().unwrap().take();
+        match result {
+          Some((false, value)) => Ok(Some(value)),
+          Some((true, _)) => Err("PERMISSION_DENIED: the keyring was not unlocked (prompt dismissed)".to_string()),
+          None => {
+            let _ = self.call(prompt.as_str(), "org.freedesktop.Secret.Prompt", "Dismiss", None, "()");
+            Err("PERMISSION_DENIED: the keyring password prompt was not answered".to_string())
+          }
+        }
+      })
+      .map_err(|e| format!("INTERNAL: {e}"))?
+  }
+
+  fn unlock(&self, objects: &[ObjectPath]) -> Result<(), String> {
+    let reply = self.call(PATH, SERVICE, "Unlock", Some(&(objects.to_vec(),).to_variant()), "(aoo)")?;
+    let (unlocked, prompt) = reply.get::<(Vec<ObjectPath>, ObjectPath)>().ok_or("INTERNAL: Unlock answered nothing")?;
+    if unlocked.len() < objects.len() {
+      self.prompt(&prompt)?;
+    }
+    Ok(())
+  }
+
+  /// The items with these attributes in any collection, the unlocked ones first.
+  fn search(&self, attributes: &HashMap<&str, &str>) -> Result<(Vec<ObjectPath>, Vec<ObjectPath>), String> {
+    let reply = self.call(PATH, SERVICE, "SearchItems", Some(&(attributes,).to_variant()), "(aoao)")?;
+    reply.get::<(Vec<ObjectPath>, Vec<ObjectPath>)>().ok_or_else(|| "INTERNAL: SearchItems answered nothing".into())
+  }
+
+  /// The first item found, unlocked.
+  fn find(&self, attributes: &HashMap<&str, &str>) -> Result<Option<ObjectPath>, String> {
+    let (unlocked, locked) = self.search(attributes)?;
+    if let Some(item) = unlocked.into_iter().next() {
+      return Ok(Some(item));
+    }
+    let Some(item) = locked.into_iter().next() else { return Ok(None) };
+    self.unlock(std::slice::from_ref(&item))?;
+    Ok(Some(item))
+  }
+
+  /// A Secret struct (oayays). Built from its children: a tuple of Rust values would box a Variant as "v".
+  fn secret(&self, value: &str) -> Variant {
+    let content_type = "text/plain; charset=utf8";
+    Variant::tuple_from_iter([self.session.to_variant(), Vec::<u8>::new().to_variant(), Variant::array_from_fixed_array(value.as_bytes()), content_type.to_variant()])
+  }
+
+  /// The "default" collection (the login keyring), created when the session has none.
+  fn default_collection(&self) -> Result<ObjectPath, String> {
+    let reply = self.call(PATH, SERVICE, "ReadAlias", Some(&("default",).to_variant()), "(o)")?;
+    let (collection,) = reply.get::<(ObjectPath,)>().ok_or("INTERNAL: ReadAlias answered nothing")?;
+    if collection.as_str() != "/" {
+      return Ok(collection);
+    }
+    let mut properties: HashMap<&str, Variant> = HashMap::new();
+    properties.insert("org.freedesktop.Secret.Collection.Label", "Login".to_variant());
+    let reply = self.call(PATH, SERVICE, "CreateCollection", Some(&(properties, "default").to_variant()), "(oo)")?;
+    let (collection, prompt) = reply.get::<(ObjectPath, ObjectPath)>().ok_or("INTERNAL: CreateCollection answered nothing")?;
+    if collection.as_str() != "/" {
+      return Ok(collection);
+    }
+    // gnome-keyring asks for the new keyring's password first; the result is the collection.
+    self.prompt(&prompt)?.and_then(|v| v.get::<ObjectPath>()).ok_or_else(|| "INTERNAL: no default keyring was created".into())
+  }
+
+  fn close(&self) {
+    let _ = self.call(self.session.as_str(), "org.freedesktop.Secret.Session", "Close", None, "()");
+  }
+}
+
+fn get(s: &Secrets, attributes: &HashMap<&str, &str>) -> Result<Option<String>, String> {
+  let Some(item) = s.find(attributes)? else { return Ok(None) };
+  let reply = s.call(item.as_str(), ITEM, "GetSecret", Some(&(s.session.clone(),).to_variant()), "((oayays))")?;
+  let ((_, _, value, _),) = reply.get::<((ObjectPath, Vec<u8>, Vec<u8>, String),)>().ok_or("INTERNAL: GetSecret answered no secret")?;
+  String::from_utf8(value).map(Some).map_err(|_| "INTERNAL: the secret is not UTF-8".to_string())
+}
+
+fn set(s: &Secrets, attributes: &HashMap<&str, &str>, value: &str, label: &str) -> Result<(), String> {
+  // An item that exists (in whichever collection) gets the new secret: no second copy.
+  if let Some(item) = s.find(attributes)? {
+    s.call(item.as_str(), ITEM, "SetSecret", Some(&Variant::tuple_from_iter([s.secret(value)])), "()")?;
+    return Ok(());
+  }
+  let collection = s.default_collection()?;
+  s.unlock(std::slice::from_ref(&collection))?;
+  let mut properties: HashMap<&str, Variant> = HashMap::new();
+  properties.insert("org.freedesktop.Secret.Item.Label", label.to_variant());
+  properties.insert("org.freedesktop.Secret.Item.Attributes", attributes.to_variant());
+  let args = Variant::tuple_from_iter([properties.to_variant(), s.secret(value), true.to_variant()]);
+  let reply = s.call(collection.as_str(), "org.freedesktop.Secret.Collection", "CreateItem", Some(&args), "(oo)")?;
+  let (item, prompt) = reply.get::<(ObjectPath, ObjectPath)>().ok_or("INTERNAL: CreateItem answered nothing")?;
+  if item.as_str() == "/" {
+    s.prompt(&prompt)?;
+  }
+  Ok(())
+}
+
+fn delete(s: &Secrets, attributes: &HashMap<&str, &str>) -> Result<(), String> {
+  let (unlocked, locked) = s.search(attributes)?;
+  if !locked.is_empty() {
+    s.unlock(&locked)?;
+  }
+  for item in unlocked.iter().chain(&locked) {
+    let reply = s.call(item.as_str(), ITEM, "Delete", None, "(o)")?;
+    if let Some((prompt,)) = reply.get::<(ObjectPath,)>() {
+      s.prompt(&prompt)?;
+    }
+  }
+  Ok(())
+}
+
+fn run(cmd: &json::V) -> Result<String, String> {
+  let op = cmd.get("op").and_then(|v| v.as_str()).unwrap_or("");
+  let text = |name: &str| cmd.get(name).and_then(|v| v.as_str()).filter(|s| !s.is_empty()).ok_or(format!("{op}: {name} must be a non-empty string"));
+  let (service, account) = (text("service")?, text("account")?);
+  let attributes = HashMap::from([("service", service), ("account", account)]);
+  let secrets = Secrets::open()?;
+  let result = match op {
+    "keychain.get" => get(&secrets, &attributes).map(|v| format!(r#"{{"value":{}}}"#, v.map_or("null".into(), |s| json::quote(&s)))),
+    "keychain.set" => {
+      let value = cmd.get("value").and_then(|v| v.as_str()).ok_or("keychain.set: value must be a string")?;
+      let label = cmd.get("label").and_then(|v| v.as_str()).map_or_else(|| format!("{service} ({account})"), str::to_string);
+      set(&secrets, &attributes, value, &label).map(|_| "null".into())
+    }
+    "keychain.delete" => delete(&secrets, &attributes).map(|_| "null".into()),
+    _ => Err(format!("unknown op {op}")),
+  };
+  secrets.close();
+  result
+}
+
+/// keychain.* ops: answered from a thread through `crate::reply` (a prompt waits for the user).
+pub fn async_op(id: u64, json_text: &str) -> bool {
+  if !json_text.contains("\"keychain.") {
+    return false;
+  }
+  let Ok(cmd) = json::parse(json_text) else { return false };
+  if !cmd.get("op").and_then(|v| v.as_str()).is_some_and(|op| op.starts_with("keychain.")) {
+    return false;
+  }
+  std::thread::spawn(move || crate::reply(id, run(&cmd)));
+  true
+}