pi-git-auth 1.1.0 → 1.1.1

package/README.md

@@ -2,8 +2,8 @@
 
 A [pi](https://github.com/badlogic/pi-mono) (coding-agent) extension that 
 gives the agent **git forges authentication** for **GitHub and GitLab**: login tokens are stored in the
-OS keyring, the active account is selected in the TUI, and every `git`
-command the agent runs is transparently authenticated with that account's
+OS keyring, switch account, and every `git`command 
+the agent runs is transparently authenticated with that account's
 token for its host. It also manages accounts and repositories through each
 service's REST API.
 
@@ -154,6 +154,28 @@ provider.
 - `credentials.json` keeps only a `wallet:v1:<accountKey>` marker per
   account; the token itself is in the keyring.
 
+#### KDE Plasma (KWallet / ksecretd)
+
+`ksecretd` fires a KWallet unlock dialog for **every** D-Bus operation on
+a locked collection, so the client is built to keep wallet access to the
+absolute minimum:
+
+- **Lookup never prompts.** A read on a locked collection returns
+  `locked` without touching the collection — no stacked prompts, no kded
+  "Repeated attempts to access a wallet have occurred" warning.
+- **Store is a single roundtrip** (delete matching items + create the new
+  one, at most one unlock attempt) and only runs when a token actually
+  changed. `/auth switch`, `status`, and plain git use perform **zero**
+  keyring writes.
+- **When the wallet is locked (or the keyring is otherwise unreachable)
+  while writing**, the token is transparently kept in the encrypted file
+  instead of leaving a dead `wallet:v1:` marker — the token stays
+  available. Once the wallet unlocks, the next token change moves it back
+  into the keyring.
+- If the wallet is locked when pi starts, the in-memory token is empty for
+  that session (git auth is disabled meanwhile) and `/auth status` says so
+  explicitly instead of showing a bare `(none)`.
+
 ### Encrypted file (fallback)
 When python3 / D-Bus / a keyring are unavailable (headless server, no
 session bus), the extension transparently falls back to an on-disk
@@ -178,8 +200,9 @@ reachable, else file), `wallet`, or `file`.
 
 - The git gate adds one regex pass per `git` command (same as any string
   rewrite) and no network calls; login adds one TUI prompt.
-- The keyring round-trip is one D-Bus exchange per account, only at load
-  and write time.
+- The keyring round-trip is one D-Bus exchange per account at load, and a
+  single upsert roundtrip **only for accounts whose token changed** at
+  write time (a `/auth switch` writes no keyring at all).
 - GitHub's details view uses a single bounded set of REST calls
   (repo meta + 5 commits + 1 recursive tree). GitLab's tree is top-level
   only (its API does not recurse), bounded to 100 entries.

package/auth.ts

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { loadStore, saveStore, maskToken, activeAccount, accountKey, purgeAccountStorage, storeBackend, type StoreData } from "./store";
+import { loadStore, saveStore, maskToken, activeAccount, accountKey, purgeAccountStorage, storeBackend, keyringUnavailableAtLoadFlag, type StoreData } from "./store";
 import { SERVICES, type Platform, type Service } from "./forge";
 
 /** The subset of ctx.ui the auth flows need. */
@@ -132,13 +132,21 @@ export function statusDetail(data: StoreData): string {
   }
   const activeKey = data.activeLogin;
   if (activeKey) lines.push("");
-  lines.push(`Store: ${storeBackend() === "keyring" ? "OS keyring (Secret Service)" : "encrypted file"}`);
+  const backend = storeBackend() === "keyring" ? "OS keyring (Secret Service)" : "encrypted file";
+  const kwLocked = storeBackend() === "keyring" && keyringUnavailableAtLoadFlag();
+  lines.push(`Store: ${backend}${kwLocked ? " (locked/unreachable on load)" : ""}`);
   if (activeKey) lines.push("");
   const active = activeKey ? data.accounts[activeKey] : undefined;
   if (active && activeKey) {
     lines.push("");
     lines.push(`Active: @${active.user ?? activeKey.slice(activeKey.indexOf(":") + 1)}  (${active.platform})`);
-    lines.push(`Token: ${maskToken(active.accessToken)}`);
+    if (!active.accessToken && kwLocked) {
+      lines.push(
+        "Token: (none) — keyring locked: the token is stored in the keyring and is available again once the wallet unlocks (git auth is disabled meanwhile)"
+      );
+    } else {
+      lines.push(`Token: ${maskToken(active.accessToken)}`);
+    }
     if (active.scopes) lines.push(`Scopes: ${active.scopes}`);
     lines.push(`Saved: ${active.savedAt}`);
   }

package/keyring.ts

@@ -8,11 +8,23 @@
  * It talks JSON over stdin/stdout, which means the secret NEVER appears in
  * a process argument list — only in the parent process's memory.
  *
+ * KWallet/ksecretd (KDE Plasma) notes:
+ *   - ksecretd triggers a KWallet unlock dialog for every D-Bus operation
+ *     on a LOCKED collection. To keep this from stacking prompts (and
+ *     tripping kded's "Repeated attempts to access a wallet have
+ *     occurred" warning):
+ *       * "lookup" on a locked collection returns {"locked": true} and
+ *         never touches the collection;
+ *       * "upsert" does delete+create in ONE D-Bus roundtrip with at most
+ *         ONE explicit unlock attempt (only when a non-empty secret is
+ *         actually being written);
+ *       * delete-only ("clear" / empty secret) never unlocks.
+ *
  * Two API generations are auto-detected at runtime by introspection:
  *   - modern 0.0.1 (gnome-keyring, kwallet --secretservice):
  *       Service.Store / SearchItems / item.GetSecret
  *   - legacy 0.0.0 (KDE ksecretd, default with KWallet 6):
- *       Collection.CreateItem / Service.SearchItems / Service.GetSecrets
+ *       Collection.CreateItem / SearchItems / Service.GetSecrets
  *
  * Fallback: when python3/dbus/keyring are unavailable (headless, no D-Bus),
  * store.ts silently keeps the on-disk AES-encrypted file format.
@@ -26,10 +38,14 @@ export const STATE_DIR = join(homedir(), ".pi", "agent", "pi-git-auth");
 const PY_PATH = join(STATE_DIR, "wallet-tool.py");
 const TIMEOUT_MS = 8000;
 
+/** Outcome of a keyring write: ok, keyring locked, or unreachable. */
+export type WalletResult = "ok" | "locked" | "unreachable";
+
 interface WalletRes {
   ok: boolean;
   secret?: string;
   api?: string;
+  locked?: boolean;
   error?: string;
 }
 
@@ -38,12 +54,22 @@ const PY = `#!/usr/bin/env python3
 
 Protocol: one JSON request on stdin, one JSON response line on stdout.
   {"cmd": "available"}
-  {"cmd": "store",  "attrs": {...}, "secret": "..."}
+  {"cmd": "upsert", "attrs": {...}, "secret": "..."}   # empty secret = delete only
   {"cmd": "lookup", "attrs": {...}}
   {"cmd": "clear",  "attrs": {...}}
 
 Auto-detects the Secret Service API generation (modern 0.0.1 vs legacy
 0.0.0/ksecretd) by introspecting the service.
+
+KWallet/ksecretd (KDE) note: every D-Bus operation on a LOCKED collection
+triggers a KWallet unlock dialog. So:
+  - "lookup" on a locked collection returns {"locked": true} and never
+    touches the collection;
+  - "upsert" does delete+create in ONE roundtrip with at most ONE explicit
+    unlock attempt, and only when a non-empty secret is written;
+  - delete-only never unlocks.
+This keeps the client from stacking unlock prompts, which is what makes
+kded warn "Repeated attempts to access a wallet have occurred".
 """
 import sys
 import json
@@ -114,12 +140,12 @@ def main():
             if str(coll) == "/":
                 out({"ok": False, "error": "no default collection in keyring"})
                 return
-            try:
-                dbusi.Unlock([coll])
-            except Exception:
-                pass
 
         def find_items():
+            """Return (item paths in unlocked collections, locked flag).
+            legacy ksecretd reports items in LOCKED collections separately;
+            touching them would fire KWallet unlock dialogs, so callers
+            get the flag instead."""
             if MODERN:
                 res = dbusi.SearchItems(
                     dbus.UInt32(0),
@@ -128,11 +154,11 @@ def main():
                     ),
                     dbus.ObjectPath("/"),
                 )
-                return [str(k) for k in res]
-            (u, _l) = dbusi.SearchItems(dbus.Dictionary(
+                return [str(k) for k in res], False
+            (u, locked) = dbusi.SearchItems(dbus.Dictionary(
                 {k: v for k, v in attrs.items()}, "ss"
             ))
-            return [str(k) for k in list(u) + list(_l)]
+            return [str(k) for k in list(u)], bool(locked)
 
         def get_content(path):
             """Return the secret bytes for an item path, or None."""
@@ -171,7 +197,32 @@ def main():
             except Exception:
                 pass
 
-        if cmd == "store":
+        if cmd in ("upsert", "store", "clear"):
+            paths, is_locked = find_items()
+            writing = cmd != "clear" and bool(secret)
+            if is_locked:
+                if not writing:
+                    # delete-only on a locked keyring: skip it rather than
+                    # prompt (best-effort purge; the file is already clean).
+                    out({"ok": False, "locked": True,
+                         "error": "keyring is locked"})
+                    return
+                # writing while locked: exactly ONE unlock attempt (one
+                # prompt), then re-check.
+                try:
+                    dbusi.Unlock([coll])
+                except Exception:
+                    pass
+                paths, is_locked = find_items()
+                if is_locked:
+                    out({"ok": False, "locked": True,
+                         "error": "keyring is locked"})
+                    return
+            for path in paths:
+                item_delete(path)
+            if cmd == "clear" or not secret:
+                out({"ok": True})
+                return
             if MODERN:
                 item = "/org/freedesktop/secrets/0/item/" + re.sub(
                     r"[^A-Za-z0-9_]", "_", "%s_%s" % (
@@ -213,7 +264,7 @@ def main():
                 )
             else:
                 coll_obj = dbus.Interface(
-                    bus.get_object(owner, str(dbusi.ReadAlias("default"))),
+                    bus.get_object(owner, str(coll)),
                     "org.freedesktop.Secret.Collection",
                 )
                 secret_arg = dbus.Struct((
@@ -236,7 +287,8 @@ def main():
             return
 
         if cmd == "lookup":
-            for path in find_items():
+            paths, is_locked = find_items()
+            for path in paths:
                 content = get_content(path)
                 if content:
                     out({
@@ -244,15 +296,15 @@ def main():
                         "secret": content.decode("utf-8", "replace"),
                     })
                     return
+            if is_locked:
+                # Item exists but its collection is locked (KWallet):
+                # report it, don't touch the collection (no unlock prompt).
+                out({"ok": False, "locked": True,
+                     "error": "keyring is locked"})
+                return
             out({"ok": False, "error": "item not found"})
             return
 
-        if cmd == "clear":
-            for path in find_items():
-                item_delete(path)
-            out({"ok": True})
-            return
-
         out({"ok": False, "error": "unknown command"})
     except Exception as e:
         msg = str(e)
@@ -319,20 +371,35 @@ export function walletAvailable(): boolean {
   return availCache;
 }
 
-/** Store (upsert) a secret. */
-export function walletStore(attrs: Record<string, string>, secret: string): boolean {
-  const r = call({ cmd: "store", attrs, secret });
-  return !!(r && r.ok);
+let lastLookupLocked = false;
+
+/**
+ * Upsert a secret for the given attrs in ONE D-Bus roundtrip: existing
+ * matching items are deleted, then (when secret is non-empty) the new item
+ * is created. An empty secret deletes only (best-effort, never prompts).
+ * "locked" = the keyring exists but is locked (KWallet): the token must be
+ * kept in the file fallback; "unreachable" = no keyring/D-Bus at all.
+ */
+export function walletUpsert(attrs: Record<string, string>, secret: string): WalletResult {
+  const r = call({ cmd: "upsert", attrs, secret });
+  if (!r) return "unreachable";
+  if (r.ok) return "ok";
+  if (r.locked) return "locked";
+  return "unreachable";
 }
 
-/** Read a secret; null when not found or the keyring is unreachable. */
+/**
+ * Read a secret; null when not found, the keyring is locked, or the
+ * keyring is unreachable. See walletWasLocked() to distinguish a locked
+ * keyring from a missing item.
+ */
 export function walletLookup(attrs: Record<string, string>): string | null {
   const r = call({ cmd: "lookup", attrs });
+  lastLookupLocked = !!(r && r.locked);
   return r && r.ok ? (r.secret ?? null) : null;
 }
 
-/** Remove every item matching attrs. No-op when none exist. */
-export function walletClear(attrs: Record<string, string>): boolean {
-  const r = call({ cmd: "clear", attrs });
-  return !!(r && r.ok);
+/** True when the last lookup failed because the keyring is locked. */
+export function walletWasLocked(): boolean {
+  return lastLookupLocked;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-git-auth",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "pi coding-agent extension: git auth for GitHub and GitLab: keyring-stored login tokens, account switching, transparent git auth, repo list/create with details overlay",
   "license": "MIT",
   "author": "Carlo Onofrio",

package/store.ts

@@ -3,7 +3,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
 import type { Platform } from "./forge";
-import { STATE_DIR, walletAvailable, walletStore, walletLookup, walletClear, walletAttrs } from "./keyring";
+import { STATE_DIR, walletAvailable, walletUpsert, walletLookup, walletAttrs } from "./keyring";
 
 /**
  * Credential persistence for pi-git-auth (multi-account, multi-service).
@@ -67,6 +67,12 @@ export interface StoreData {
 
 let cache: StoreData | null = null;
 let keyCache: Buffer | null = null;
+/** Stored strings (markers/envelopes) from the last file read/write. */
+let diskData: StoreData | null = null;
+/** Plaintext tokens as last persisted, per account key ("" = unreadable). */
+let storedPlaintext: Record<string, string> = {};
+/** A `wallet:v1:` token could not be read on load (keyring locked/absent). */
+let keyringUnavailableAtLoad = false;
 
 const ENC_PREFIX = "enc:v1:";
 const WALLET_PREFIX = "wallet:v1:";
@@ -163,22 +169,35 @@ function decryptToken(enc: string): string {
 // Store API
 // ---------------------------------------------------------------------------
 
-function persist(data: StoreData): void {
-  // The in-memory copy holds plaintext; for each account the token is
-  // stored in the backend and the file keeps only a marker/envelope.
+/**
+ * Persist the in-memory (plaintext) state. Only accounts whose token
+ * changed since the last persist are (re)written to the backend; the
+ * others keep their on-disk marker/envelope untouched. This matters on
+ * KDE/ksecretd: a keyring write is the only operation that may trigger
+ * the KWallet unlock dialog, so e.g. `/auth switch` performs zero
+ * keyring writes (no prompts, no "repeated wallet access" warnings).
+ * When the keyring is locked/unreachable the token is kept in the
+ * encrypted file instead of leaving a dead `wallet:v1:` marker behind.
+ */
+function persist(data: StoreData, forceStore = false): void {
   const mode = storeMode();
   const accounts: Record<string, AccountRecord> = {};
+  const nowPlaintext: Record<string, string> = {};
   for (const [k, a] of Object.entries(data.accounts)) {
+    const changed = forceStore || storedPlaintext[k] !== a.accessToken;
+    const diskStored = diskData?.accounts[k]?.accessToken;
     let stored: string;
-    if (mode === "wallet") {
-      // Clear-then-store keeps the keyring free of duplicate items.
-      const attrs = recAttrs(a, k);
-      walletClear(attrs);
-      stored = walletStore(attrs, a.accessToken) ? WALLET_PREFIX + k : encryptToken(a.accessToken);
+    if (changed && a.accessToken) {
+      // Single keyring roundtrip (delete matching items + create).
+      const r = mode === "wallet" ? walletUpsert(recAttrs(a, k), a.accessToken) : null;
+      stored = r === "ok" ? WALLET_PREFIX + k : encryptToken(a.accessToken);
+    } else if (diskStored) {
+      stored = diskStored; // unchanged: keep the existing marker/envelope
     } else {
-      stored = encryptToken(a.accessToken);
+      stored = a.accessToken ? encryptToken(a.accessToken) : "";
     }
     accounts[k] = { ...a, accessToken: stored };
+    nowPlaintext[k] = a.accessToken;
   }
   const out: StoreData = {
     accounts,
@@ -189,6 +208,9 @@ function persist(data: StoreData): void {
   writeFileSync(tmp, JSON.stringify(out, null, 2) + "\n", { mode: 0o600 });
   renameSync(tmp, CREDENTIALS_FILE);
   chmodSync(CREDENTIALS_FILE, 0o600);
+  diskData = out;
+  storedPlaintext = nowPlaintext;
+  cache = data;
 }
 
 export function loadStore(): StoreData {
@@ -201,6 +223,11 @@ export function loadStore(): StoreData {
   } catch {
     raw = {};
   }
+  // Deep snapshot BEFORE absorb() mutates records in place — diskData must
+  // keep the on-disk stored strings (markers/envelopes), never the
+  // plaintext tokens that absorb decrypts into the same objects.
+  diskData = raw.accounts && typeof raw.accounts === "object" ? JSON.parse(JSON.stringify(raw)) : null;
+  keyringUnavailableAtLoad = false;
   const data: StoreData = { accounts: {} };
   let migrated = false;
 
@@ -209,7 +236,10 @@ export function loadStore(): StoreData {
     if (rec.accessToken.startsWith(WALLET_PREFIX)) {
       const got = walletLookup(recAttrs(rec, key));
       if (got === null) {
-        rec.accessToken = ""; // keyring unreachable/cleared: don't crash, don't leak
+        // keyring locked/cleared: keep the marker on disk, run this
+        // process without the token, and flag it for the status output.
+        rec.accessToken = "";
+        keyringUnavailableAtLoad = true;
       } else {
         rec.accessToken = got;
       }
@@ -229,6 +259,7 @@ export function loadStore(): StoreData {
       migrated = true;
     }
     data.accounts[key] = rec as AccountRecord;
+    storedPlaintext[key] = (rec as AccountRecord).accessToken;
   };
 
   if (raw.accounts && typeof raw.accounts === "object") {
@@ -253,7 +284,7 @@ export function loadStore(): StoreData {
       // Keep a rollback copy of the pre-migration file (still 0600, no
       // new secrets — it only contains ciphertexts/markers).
       if (hadFile && existsSync(CREDENTIALS_FILE)) copyFileSync(CREDENTIALS_FILE, CREDENTIALS_FILE + ".bak");
-      persist(cache);
+      persist(cache, true); // force re-store under the current backend
     } catch {
       /* best-effort migration */
     }
@@ -262,14 +293,20 @@ export function loadStore(): StoreData {
 }
 
 export function saveStore(data: StoreData): void {
-  cache = data;
   persist(data);
 }
 
+/** True when a `wallet:v1:` token could not be read on load (keyring
+ *  locked or unreachable) — the in-memory token for that account is "". */
+export function keyringUnavailableAtLoadFlag(): boolean {
+  return keyringUnavailableAtLoad;
+}
+
 /** Remove one account's keyring item (idempotent, best-effort). */
 export function purgeAccountStorage(key: string, rec?: AccountRecord | null): void {
   try {
-    if (rec) walletClear(recAttrs(rec, key));
+    // Empty secret = delete-only: best-effort, never triggers a prompt.
+    if (rec) walletUpsert(recAttrs(rec, key), "");
   } catch {
     /* best-effort */
   }
@@ -280,13 +317,15 @@ export function clearStore(): void {
   try {
     if (cache) {
       for (const [k, rec] of Object.entries(cache.accounts)) {
-        walletClear(recAttrs(rec, k));
+        walletUpsert(recAttrs(rec, k), "");
       }
     }
   } catch {
     /* best-effort */
   }
   cache = { accounts: {} };
+  diskData = null;
+  storedPlaintext = {};
   try {
     rmSync(CREDENTIALS_FILE);
   } catch {