pi-git-auth 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carlo Onofrio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,192 @@
+# pi-git-auth
+
+A pi (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
+token for its host. It also manages accounts and repositories through each
+service's REST API.
+
+No npm dependencies — only pi's bundled packages and Node built-ins.
+
+## Install
+
+As a pi package:
+
+```
+pi install npm:pi-git-auth
+```
+
+Or from git:
+
+```
+pi install git:github.com/comicrocharly/pi-git-auth
+```
+
+Or manually: copy the `.ts` files into
+`~/.pi/agent/extensions/pi-git-auth/`. No build step — pi loads the
+TypeScript directly.
+
+## How it works
+
+- **Login** stores a token per (service, login) pair.
+- One account is **active** at a time. Every action — git auth, repos,
+  create, the LLM tool — uses **the REST API of the active account's
+  service**, so switching accounts also switches the backend.
+- A `tool_call` hook watches every `bash` invocation. When an active
+  account exists and the command runs `git`, the command is rewritten to
+  authenticate that account's host (see [git auth](#git-auth)).
+
+## Layout
+
+```
+index.ts     extension entry: git-gate hook, /auth command, `auth` LLM tool
+auth.ts      login/logout/switch flows (per service), status text
+commands.ts  /auth subcommands + interactive TUI menu
+store.ts     multi-account credential persistence (keyring or file)
+keyring.ts   OS keyring backend (freedesktop Secret Service) + python D-Bus client
+forge.ts     service abstraction: normalized types + GitHub/GitLab registry
+github.ts    GitHub REST client
+gitlab.ts    GitLab REST client
+details.ts   read-only repo details overlay (tree + commits + metadata)
+git-gate.ts  command rewriting that injects the token for a host
+```
+
+## Usage
+
+### /auth
+With no argument an interactive TUI menu is shown (status / login /
+logout / switch account / repos / create); each action prompts for
+anything missing.
+
+Multiple accounts are supported, across GitHub **and** GitLab. One
+account is **active** at a time.
+
+### /auth status
+List all stored accounts (service + active marker), the active storage
+backend, plus the active account's details (masked token, scopes).
+
+### /auth login
+Pick a service (GitHub or GitLab), then paste a token straight into the
+TUI — the token-creation page is opened in the browser.
+
+- GitHub: classic PAT `ghp_…` (scopes: `repo`, `user:email`) or a
+  fine-grained `github_pat_…` token.
+- GitLab: personal access token `glpat-…` (scope: `api`).
+
+Verified against the service (`GET /user` / `GET /api/v4/user`) before
+storing. Accounts are keyed by service+login: logging in again with the
+same pair replaces its token. The logged-in account becomes the active
+one.
+
+### /auth logout
+Picks an account to remove. If it was the active one, another remaining
+account becomes active (or none, if it was the last).
+
+### /auth switch
+Picks a stored account and makes it the active one.
+
+### /auth repos [org]
+Lists your repos (or an org's/group's) **on the active account's service**.
+Picking one opens a details overlay: description, branch/size/stars/forks/
+last-push, a two-level file tree, and the five latest commits. Close with
+esc/enter/q.
+
+### /auth create [org/]name
+Creates a repo on the active account's service (prompts for visibility
+and description).
+
+### LLM tool: `auth`
+The model can call `auth` with actions `status | switch | list | create`
+(plus an `account` parameter for `switch`; `"platform:login"`
+disambiguates a login that exists on both services). These are REST API
+operations run against the active account's service — the git gate can't
+do them. For clone/push the model just runs `git` via bash: the harness
+authenticates the active account's host automatically (the git gate), so
+no tool action is needed for git.
+
+Repository deletion is intentionally not exposed (safety).
+
+## git auth
+
+A `tool_call` hook watches every `bash` tool invocation. If an active
+account is stored and the command runs `git`, it rewrites the command to
+use that account's token for the account's host (`github.com` or
+`gitlab.com`):
+
+```
+export GIT_TERMINAL_PROMPT=0 \
+  GIT_CONFIG_COUNT=1 \
+  GIT_CONFIG_KEY_0="url.https://x-access-token:<token>@<host>/.insteadOf" \
+  GIT_CONFIG_VALUE_0="https://<host>/" && <command>
+```
+
+Forging hosts' git-over-HTTPS endpoints ignore `Authorization` headers
+and only accept URL-embedded credentials, hence the `insteadOf` rewrite.
+Only the active host is touched; other remotes are untouched.
+
+## Token storage
+
+Tokens are **never stored plaintext on disk**. Two backends are
+available; the extension picks one at load time.
+
+### OS keyring (preferred)
+The token lives in the session keyring, addressed by the
+[freedesktop Secret Service API](https://specifications.freedesktop.org/secret-service/)
+(`org.freedesktop.secrets` over D-Bus). This covers KWallet (via
+`ksecretd`), GNOME Keyring, KeePassXC, and any other Secret Service
+provider.
+
+- The embedded python3 client (a small script that `keyring.ts` keeps
+  in sync in the state dir) opens a D-Bus session and talks
+  **JSON over stdin/stdout**. The token therefore never appears in a
+  process argument list — only in the parent's memory.
+- The client **auto-detects the Secret Service API generation** by
+  introspecting the service: modern 0.0.1
+  (`Store`/`GetSecret`) for gnome-keyring / `kwallet --secretservice`,
+  or legacy 0.0.0 (`Collection.CreateItem`/`GetSecrets`) for KDE
+  `ksecretd`. Both are implemented.
+- `credentials.json` keeps only a `wallet:v1:<accountKey>` marker per
+  account; the token itself is in the keyring.
+
+### 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
+AES-256-GCM envelope:
+
+- `~/.pi/agent/pi-git-auth/credentials.json` (0600) holds each token as
+  an `enc:v1:<base64>` envelope.
+- The key lives in a separate 0600 `key` file (0700 dir).
+
+### Migration
+Moving from the old plaintext/`enc:v1:` layout to the keyring is
+transparent. On first load, any legacy token is read, written to the
+keyring, and the file is rewritten with `wallet:v1:` markers. A `.bak`
+copy of the pre-migration file is kept (ciphertext/markers only, no
+plaintext).
+
+### Override
+`PI_GIT_AUTH_STORE` forces the backend: `auto` (default — keyring when
+reachable, else file), `wallet`, or `file`.
+
+## Performance
+
+- 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.
+- 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.
+
+## Limits
+
+- GitHub: `github.com` only (no GitHub Enterprise).
+- GitLab: `gitlab.com` only (no self-hosted instances).
+- GitLab does not expose project size or per-file sizes via this API;
+  the details overlay simply omits them.
+- GitLab's repository tree is top-level only (the API ignores `recursive`),
+  so nested directories are not listed in the details overlay.
+- GitLab project list for an org tries the group first, then a user.
+- Keyring storage requires a D-Bus session bus and a Secret Service
+  provider; otherwise the encrypted-file fallback is used.

package/auth.ts

@@ -0,0 +1,146 @@
+import { spawn } from "node:child_process";
+import { loadStore, saveStore, maskToken, activeAccount, accountKey, purgeAccountStorage, storeBackend, type StoreData } from "./store";
+import { SERVICES, type Platform, type Service } from "./forge";
+
+/** The subset of ctx.ui the auth flows need. */
+export interface UiLike {
+  input(title: string, placeholder?: string): Promise<string | undefined>;
+  notify(message: string, type?: "info" | "warning" | "error"): void;
+}
+
+function fail(ui: UiLike, e: unknown): void {
+  ui.notify(`Login failed: ${e instanceof Error ? e.message : String(e)}`, "error");
+}
+
+function openBrowser(url: string): void {
+  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "explorer" : "xdg-open";
+  try {
+    const p = spawn(cmd, [url], { stdio: "ignore", detached: true });
+    p.on("error", () => {});
+    p.unref();
+  } catch {
+    /* headless: the URL is shown in the notify message anyway */
+  }
+}
+
+/** Display name for an account key: the login part, without platform. */
+export function accountName(data: StoreData, key: string): string {
+  return data.accounts[key]?.user ?? key.slice(key.indexOf(":") + 1);
+}
+
+/**
+ * Login for a specific service (GitHub or GitLab). The account is keyed
+ * by platform+login: logging in again with the same pair replaces its
+ * token; either way the account becomes the active one.
+ */
+export async function loginWithPastedToken(ui: UiLike, service: Service): Promise<void> {
+  openBrowser(service.tokenUrl);
+  ui.notify(`Create a ${service.label} token here: ${service.tokenUrl}  (scopes: ${service.scopesHint})`, "info");
+  const raw = (await ui.input(`Paste ${service.label} token (page opened in browser)`, service.tokenPlaceholder))?.trim();
+  if (!raw) {
+    ui.notify("Login cancelled", "info");
+    return;
+  }
+  ui.notify("Verifying token…", "info");
+  let user;
+  try {
+    user = await service.verify(raw);
+  } catch (e) {
+    fail(ui, e);
+    return;
+  }
+  const data = loadStore();
+  const key = accountKey(service.id, user.login);
+  const isExisting = !!data.accounts[key];
+  data.accounts[key] = {
+    type: "pat",
+    platform: service.id,
+    accessToken: raw,
+    user: user.login,
+    scopes: user.scopes,
+    savedAt: new Date().toISOString(),
+  };
+  data.activeLogin = key;
+  saveStore(data);
+  ui.notify(
+    isExisting
+      ? `Token updated for @${user.login} (${service.id}) — now active`
+      : `Logged in as @${user.login} (${service.id}) — now active`,
+    "info",
+  );
+}
+
+/**
+ * Remove one stored account. If it was active, another remaining account
+ * becomes active (or none when it was the last).
+ */
+export function removeAccount(key: string): void {
+  const data = loadStore();
+  const rec = data.accounts[key];
+  delete data.accounts[key];
+  purgeAccountStorage(key, rec); // drop the keyring item, if any
+  if (data.activeLogin === key) {
+    const rest = Object.keys(data.accounts);
+    data.activeLogin = rest.length > 0 ? rest[0] : undefined;
+  }
+  saveStore(data);
+}
+
+/** Make an account the active one. Returns false for unknown keys. */
+export function setActiveAccount(key: string): boolean {
+  const data = loadStore();
+  if (!data.accounts[key]) return false;
+  if (data.activeLogin === key) return true;
+  data.activeLogin = key;
+  saveStore(data);
+  return true;
+}
+
+/**
+ * Resolve an account query ("login" or "platform:login") to stored keys.
+ * [] = unknown; >1 = ambiguous (same login on several platforms).
+ */
+export function findAccounts(query: string): string[] {
+  const q = query.trim().toLowerCase();
+  const keys = Object.keys(loadStore().accounts);
+  if (q.includes(":")) {
+    const key = accountKey(q.slice(0, q.indexOf(":")) as Platform, q.slice(q.indexOf(":") + 1));
+    return keys.includes(key) ? [key] : [];
+  }
+  return keys.filter((k) => k.endsWith(`:${q}`));
+}
+
+/** Service (REST API) of the active account, or undefined. */
+export function activeService(data: StoreData): Service | undefined {
+  const acc = activeAccount(data);
+  return acc ? SERVICES[acc.platform] : undefined;
+}
+
+/** Human-readable status block: all accounts, details for the active one. */
+export function statusDetail(data: StoreData): string {
+  const keys = Object.keys(data.accounts);
+  if (keys.length === 0) return "No git accounts. Run /auth login.";
+  const lines = ["Git accounts:"];
+  for (const k of keys) {
+    const a = data.accounts[k];
+    const star = data.activeLogin === k ? "*" : " ";
+    lines.push(
+      `  ${star} @${a?.user ?? k.slice(k.indexOf(":") + 1)}  (${a?.platform ?? "github"})${
+        data.activeLogin === k ? "  (active)" : ""
+      }`,
+    );
+  }
+  const activeKey = data.activeLogin;
+  if (activeKey) lines.push("");
+  lines.push(`Store: ${storeBackend() === "keyring" ? "OS keyring (Secret Service)" : "encrypted file"}`);
+  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.scopes) lines.push(`Scopes: ${active.scopes}`);
+    lines.push(`Saved: ${active.savedAt}`);
+  }
+  return lines.join("\n");
+}

package/commands.ts

@@ -0,0 +1,208 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { loadStore, activeAccount, type StoreData } from "./store";
+import { SERVICES, type Service, type TreeEntry } from "./forge";
+import { buildDetailsText, RepoDetailsPanel } from "./details";
+import { activeService, accountName, loginWithPastedToken, removeAccount, setActiveAccount, statusDetail } from "./auth";
+
+type Ctx = ExtensionCommandContext;
+
+async function showStatus(ctx: Ctx): Promise<void> {
+  const data = loadStore();
+  if (Object.keys(data.accounts).length === 0) {
+    ctx.ui.notify("git auth: not connected — run /auth login", "info");
+  } else {
+    ctx.ui.notify(statusDetail(data), "info");
+  }
+}
+
+async function doLogin(ctx: Ctx): Promise<void> {
+  const pick = await ctx.ui.select("git auth — which service?", [SERVICES.github.label, SERVICES.gitlab.label]);
+  const service: Service = pick === SERVICES.gitlab.label ? SERVICES.gitlab : SERVICES.github;
+  await loginWithPastedToken(ctx.ui, service);
+}
+
+function accountLabels(data: StoreData): string[] {
+  return Object.keys(data.accounts).map(
+    (k) =>
+      `@${data.accounts[k]?.user ?? k.slice(k.indexOf(":") + 1)}  (${data.accounts[k]?.platform ?? "github"})${
+        data.activeLogin === k ? "  (current)" : ""
+      }`,
+  );
+}
+
+async function doSwitch(ctx: Ctx): Promise<void> {
+  const data = loadStore();
+  if (Object.keys(data.accounts).length === 0) {
+    ctx.ui.notify("No git accounts — run /auth login", "info");
+    return;
+  }
+  const keys = Object.keys(data.accounts);
+  const labels = accountLabels(data);
+  const picked = await ctx.ui.select("git auth — set active account", labels);
+  const idx = labels.indexOf(picked ?? "");
+  if (idx < 0) return;
+  const key = keys[idx];
+  if (setActiveAccount(key)) {
+    ctx.ui.notify(
+      `Active account: @${accountName(data, key)} (${data.accounts[key]?.platform ?? "github"})`,
+      "info",
+    );
+  }
+}
+
+async function doLogout(ctx: Ctx): Promise<void> {
+  const data = loadStore();
+  if (Object.keys(data.accounts).length === 0) {
+    ctx.ui.notify("No git accounts logged in", "info");
+    return;
+  }
+  const keys = Object.keys(data.accounts);
+  const labels = accountLabels(data);
+  const picked = await ctx.ui.select("git auth — pick an account to remove", labels);
+  const idx = labels.indexOf(picked ?? "");
+  if (idx < 0) return;
+  const key = keys[idx];
+  const ok = await ctx.ui.confirm("git auth logout", `Remove @${accountName(data, key)} (${data.accounts[key]?.platform})?`);
+  if (!ok) return;
+  removeAccount(key);
+  ctx.ui.notify(`Removed @${accountName(data, key)}`, "info");
+}
+
+/** Active account + its service, or a "not connected" notice. */
+function requireActive(ctx: Ctx): { token: string; service: Service } | undefined {
+  const data = loadStore();
+  const acc = activeAccount(data);
+  const service = activeService(data);
+  if (!acc?.accessToken || !service) {
+    ctx.ui.notify("git auth: not connected — run /auth login", "warning");
+    return undefined;
+  }
+  return { token: acc.accessToken, service };
+}
+
+async function doRepos(ctx: Ctx, restArg: string): Promise<void> {
+  const active = requireActive(ctx);
+  if (!active) return;
+  const org = restArg || undefined;
+  try {
+    const repos = await active.service.listRepos(active.token, org);
+    if (repos.length === 0) {
+      ctx.ui.notify(org ? `No repos in org ${org}` : "No repositories found", "info");
+      return;
+    }
+    const labels = repos.map((r) => `${r.fullName} [${r.private ? "private" : "public"}]`);
+    const picked = await ctx.ui.select(
+      `Repositories${org ? ` (${org})` : " (owned)"} — pick one:`,
+      labels,
+    );
+    const idx = labels.indexOf(picked ?? "");
+    if (idx >= 0) {
+      await showRepoDetails(ctx, active.service, active.token, repos[idx].fullName);
+    }
+  } catch (e) {
+    ctx.ui.notify(`${active.service.label} error: ${e instanceof Error ? e.message : String(e)}`, "error");
+  }
+}
+
+/** Fetch repo metadata, latest commits and tree, then show a scrollable details overlay. */
+async function showRepoDetails(ctx: Ctx, service: Service, token: string, fullName: string): Promise<void> {
+  try {
+    const [repo, commits] = await Promise.all([service.meta(token, fullName), service.commits(token, fullName, 5)]);
+    let tree: TreeEntry[] = [];
+    if (commits.length > 0) {
+      try {
+        tree = await service.tree(token, fullName, repo.defaultBranch);
+      } catch {
+        tree = []; // non-fatal: details still shown without the tree
+      }
+    }
+    const { title, lines } = buildDetailsText(repo, commits, tree);
+    await ctx.ui.custom<void>(
+      (tui, theme, _keybindings, done) =>
+        new RepoDetailsPanel(
+          title,
+          lines,
+          theme,
+          () => tui.terminal.rows,
+          () => done(undefined),
+          () => tui.requestRender(),
+        ),
+      {
+        overlay: true,
+        overlayOptions: { width: "65%", minWidth: 64, maxHeight: "80%", margin: 1 },
+      },
+    );
+  } catch (e) {
+    ctx.ui.notify(`${service.label} error: ${e instanceof Error ? e.message : String(e)}`, "error");
+  }
+}
+
+async function doCreate(ctx: Ctx, restArg: string): Promise<void> {
+  const active = requireActive(ctx);
+  if (!active) return;
+  let fullName = restArg.trim();
+  if (!fullName) {
+    fullName = (await ctx.ui.input("New repository name", "name or owner/name"))?.trim() ?? "";
+  }
+  if (!fullName) return;
+  const sep = fullName.indexOf("/");
+  const org = sep > 0 ? fullName.slice(0, sep) : undefined;
+  const name = sep > 0 ? fullName.slice(sep + 1) : fullName;
+  if (!name) return;
+
+  const visibility = (await ctx.ui.select(`Create ${org ? `${org}/` : ""}${name}`, ["private", "public"])) ?? "private";
+  const description = await ctx.ui.input("Description (optional, Enter to skip)", "");
+
+  try {
+    const repo = await active.service.createRepo(active.token, name, {
+      org,
+      private: visibility === "private",
+      description: description?.trim() || undefined,
+    });
+    ctx.ui.notify(`Created ${repo.fullName} → ${repo.htmlUrl}`, "info");
+  } catch (e) {
+    ctx.ui.notify(`${active.service.label} error: ${e instanceof Error ? e.message : String(e)}`, "error");
+  }
+}
+
+const MENU: { label: string; key: string }[] = [
+  { label: "status", key: "status" },
+  { label: "login", key: "login" },
+  { label: "logout", key: "logout" },
+  { label: "switch account", key: "switch" },
+  { label: "repos [org]", key: "repos" },
+  { label: "create [org/]name", key: "create" },
+];
+
+/**
+ * /auth [status|login|logout|switch|repos [org]|create [org/]name]
+ *
+ * Without arguments (or with an unknown one) an interactive TUI menu is
+ * shown; each option runs the matching action, which prompts for any
+ * missing arguments itself. `login` offers GitHub and GitLab; every other
+ * action uses the service of the active account.
+ */
+export async function handleAuthCommand(args: string, ctx: Ctx): Promise<void> {
+  const actions: Record<string, () => Promise<void>> = {
+    status: () => showStatus(ctx),
+    login: () => doLogin(ctx),
+    logout: () => doLogout(ctx),
+    switch: () => doSwitch(ctx),
+    repos: () => doRepos(ctx, restArg),
+    create: () => doCreate(ctx, restArg),
+  };
+
+  const [sub, ...rest] = (args ?? "").trim().split(/\s+/);
+  const arg = (sub ?? "").toLowerCase();
+  const restArg = rest.join(" ");
+
+  let chosen = arg && actions[arg] ? arg : undefined;
+  if (!chosen) {
+    const pick = await ctx.ui.select("git auth — pick an action", MENU.map((m) => m.label));
+    chosen = MENU.find((m) => m.label === pick)?.key;
+  }
+
+  if (chosen) {
+    await actions[chosen]();
+  }
+}