azdo-cli 0.10.0-develop.213 → 0.10.0-develop.233

package/README.md

@@ -16,7 +16,7 @@ Azure DevOps CLI focused on work item read/write workflows.
 - Check branch pull request status, open PRs to `develop`, and review active comments (`pr`)
 - Persist org/project/default fields in local config (`config`)
 - List all fields of a work item (`list-fields`)
-- Store PAT in OS credential store (or use `AZDO_PAT`)
+- Store a PAT per Azure DevOps organization in the OS credential store via `azdo auth` (or use `AZDO_PAT`). Inspect with `azdo auth status`, remove with `azdo auth logout`. See [docs/authentication.md](docs/authentication.md).
 
 ## Installation
 

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command as Command14 } from "commander";
+import { Command as Command15 } from "commander";
 
 // src/version.ts
 import { readFileSync } from "fs";
@@ -367,42 +367,182 @@ import { dirname as dirname2, join } from "path";
 
 // src/services/credential-store.ts
 import { Entry } from "@napi-rs/keyring";
-var SERVICE = "azdo-cli";
-var ACCOUNT = "pat";
-async function getPat() {
+
+// src/types/credential.ts
+var CredentialStoreUnavailableError = class extends Error {
+  backend;
+  constructor(backend, cause) {
+    super(`OS secret backend unavailable (${backend}). Install the platform's credential service and try again.`);
+    this.name = "CredentialStoreUnavailableError";
+    this.backend = backend;
+    if (cause instanceof Error) {
+      this.cause = cause;
+    }
+  }
+};
+
+// src/services/audit-log.ts
+import fs from "fs";
+import os from "os";
+import path from "path";
+function getAuditLogPath() {
+  return path.join(os.homedir(), ".azdo", "audit.log");
+}
+function ensureDirWithPerms(dir) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true, mode: 448 });
+    return;
+  }
   try {
-    const entry = new Entry(SERVICE, ACCOUNT);
-    return entry.getPassword();
+    fs.chmodSync(dir, 448);
   } catch {
-    return null;
   }
 }
-async function storePat(pat) {
+function ensureFileWithPerms(file) {
+  if (!fs.existsSync(file)) {
+    fs.writeFileSync(file, "", { mode: 384 });
+    return;
+  }
   try {
-    const entry = new Entry(SERVICE, ACCOUNT);
-    entry.setPassword(pat);
-    return true;
+    fs.chmodSync(file, 384);
   } catch {
-    return false;
   }
 }
-async function deletePat() {
+function appendAuthAuditEvent(input) {
+  const auditLog = getAuditLogPath();
+  const dir = path.dirname(auditLog);
+  ensureDirWithPerms(dir);
+  ensureFileWithPerms(auditLog);
+  const record = {
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    event: input.event,
+    org: input.org,
+    backend: input.backend,
+    ...input.masked_pat !== void 0 ? { masked_pat: input.masked_pat } : {}
+  };
+  fs.appendFileSync(auditLog, `${JSON.stringify(record)}
+`);
+}
+function readAuditEvents() {
+  const auditLog = getAuditLogPath();
+  if (!fs.existsSync(auditLog)) {
+    return [];
+  }
+  const contents = fs.readFileSync(auditLog, "utf8");
+  const out = [];
+  for (const line of contents.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (parsed && typeof parsed === "object" && typeof parsed.event === "string") {
+        out.push(parsed);
+      }
+    } catch {
+    }
+  }
+  return out;
+}
+
+// src/services/config-store.ts
+import fs2 from "fs";
+import path2 from "path";
+import os2 from "os";
+var SETTINGS = [
+  {
+    key: "org",
+    description: "Azure DevOps organization name",
+    type: "string",
+    example: "mycompany",
+    required: true
+  },
+  {
+    key: "project",
+    description: "Azure DevOps project name",
+    type: "string",
+    example: "MyProject",
+    required: true
+  },
+  {
+    key: "fields",
+    description: "Extra work item fields to include (comma-separated reference names)",
+    type: "string[]",
+    example: "System.Tags,Custom.Priority",
+    required: false
+  },
+  {
+    key: "markdown",
+    description: "Convert rich text fields to markdown on display",
+    type: "boolean",
+    example: "true",
+    required: false
+  }
+];
+var VALID_KEYS = SETTINGS.map((s) => s.key);
+function getConfigPath() {
+  return path2.join(os2.homedir(), ".azdo", "config.json");
+}
+function loadConfig() {
+  const configPath = getConfigPath();
+  let raw;
+  try {
+    raw = fs2.readFileSync(configPath, "utf-8");
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return {};
+    }
+    throw err;
+  }
   try {
-    const entry = new Entry(SERVICE, ACCOUNT);
-    entry.deletePassword();
-    return true;
+    return JSON.parse(raw);
   } catch {
-    return false;
+    process.stderr.write(`Warning: Config file ${configPath} contains invalid JSON. Using defaults.
+`);
+    return {};
+  }
+}
+function saveConfig(config) {
+  const configPath = getConfigPath();
+  const dir = path2.dirname(configPath);
+  fs2.mkdirSync(dir, { recursive: true });
+  fs2.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+}
+function validateKey(key) {
+  if (!VALID_KEYS.includes(key)) {
+    throw new Error(`Unknown setting key "${key}". Valid keys: ${VALID_KEYS.join(", ")}`);
   }
 }
+function getConfigValue(key) {
+  validateKey(key);
+  const config = loadConfig();
+  return config[key];
+}
+function setConfigValue(key, value) {
+  validateKey(key);
+  const config = loadConfig();
+  if (value === "") {
+    delete config[key];
+  } else if (key === "markdown") {
+    if (value !== "true" && value !== "false") {
+      throw new Error(`Invalid value "${value}" for markdown. Must be "true" or "false".`);
+    }
+    config.markdown = value === "true";
+  } else if (key === "fields") {
+    config.fields = value.split(",").map((s) => s.trim());
+  } else {
+    config[key] = value;
+  }
+  saveConfig(config);
+}
+function unsetConfigValue(key) {
+  validateKey(key);
+  const config = loadConfig();
+  delete config[key];
+  saveConfig(config);
+}
 
-// src/services/auth.ts
-var PAT_PROMPT = "Enter your Azure DevOps PAT: ";
+// src/services/auth-masking.ts
 var VISIBLE_CHARS = 5;
-function normalizePat(rawPat) {
-  const trimmedPat = rawPat.trim();
-  return trimmedPat.length > 0 ? trimmedPat : null;
-}
 function maskedDisplay(pat) {
   if (pat.length <= VISIBLE_CHARS * 2) {
     return pat;
@@ -410,6 +550,142 @@ function maskedDisplay(pat) {
   const hiddenCount = pat.length - VISIBLE_CHARS * 2;
   return pat.slice(0, VISIBLE_CHARS) + "*".repeat(hiddenCount) + pat.slice(-VISIBLE_CHARS);
 }
+function normalizePat(rawPat) {
+  const trimmedPat = rawPat.trim();
+  return trimmedPat.length > 0 ? trimmedPat : null;
+}
+
+// src/services/credential-store.ts
+var SERVICE = "azdo-cli";
+var LEGACY_ACCOUNT = "pat";
+function accountFor(org) {
+  return `pat:${org}`;
+}
+function probeBackend() {
+  switch (process.platform) {
+    case "win32":
+      return "windows-credential-manager";
+    case "darwin":
+      return "macos-keychain";
+    case "linux":
+      return "linux-libsecret";
+    default:
+      return "unknown";
+  }
+}
+function wrapUnavailable(fn) {
+  try {
+    return fn();
+  } catch (err) {
+    throw new CredentialStoreUnavailableError(probeBackend(), err);
+  }
+}
+var legacyUnsetNoticeEmitted = false;
+function emitLegacyUnsetNoticeOnce() {
+  if (legacyUnsetNoticeEmitted) return;
+  legacyUnsetNoticeEmitted = true;
+  process.stderr.write(
+    'A legacy PAT exists in the OS vault from a previous azdo-cli version, but no "org" is set in config. Run `azdo auth --org <name>` to re-store it under the per-org key, then `azdo clear-pat` to remove the legacy slot.\n'
+  );
+}
+async function maybeMigrateLegacy(targetOrg) {
+  const config = loadConfig();
+  if (!config.org || config.org !== targetOrg) {
+    if (!config.org) {
+      let legacyExists;
+      try {
+        const legacyEntry2 = new Entry(SERVICE, LEGACY_ACCOUNT);
+        legacyExists = legacyEntry2.getPassword() !== null;
+      } catch {
+        legacyExists = false;
+      }
+      if (legacyExists) {
+        emitLegacyUnsetNoticeOnce();
+      }
+    }
+    return null;
+  }
+  const newEntry = new Entry(SERVICE, accountFor(targetOrg));
+  const existingNew = wrapUnavailable(() => newEntry.getPassword());
+  if (existingNew !== null) {
+    return null;
+  }
+  const legacyEntry = new Entry(SERVICE, LEGACY_ACCOUNT);
+  const legacy = wrapUnavailable(() => legacyEntry.getPassword());
+  if (legacy === null) {
+    return null;
+  }
+  wrapUnavailable(() => {
+    newEntry.setPassword(legacy);
+    legacyEntry.deletePassword();
+  });
+  appendAuthAuditEvent({
+    event: "auth.store",
+    org: targetOrg,
+    backend: probeBackend(),
+    masked_pat: maskedDisplay(legacy)
+  });
+  process.stderr.write(`Migrated legacy PAT to org ${targetOrg}.
+`);
+  return legacy;
+}
+async function getPat(org) {
+  const entry = new Entry(SERVICE, accountFor(org));
+  const value = wrapUnavailable(() => entry.getPassword());
+  if (value !== null) {
+    return value;
+  }
+  const migrated = await maybeMigrateLegacy(org);
+  return migrated;
+}
+async function storePat(org, pat) {
+  const entry = new Entry(SERVICE, accountFor(org));
+  wrapUnavailable(() => entry.setPassword(pat));
+  appendAuthAuditEvent({
+    event: "auth.store",
+    org,
+    backend: probeBackend(),
+    masked_pat: maskedDisplay(pat)
+  });
+}
+async function deletePat(org) {
+  const entry = new Entry(SERVICE, accountFor(org));
+  const existing = wrapUnavailable(() => entry.getPassword());
+  if (existing === null) {
+    return false;
+  }
+  wrapUnavailable(() => entry.deletePassword());
+  appendAuthAuditEvent({
+    event: "auth.delete",
+    org,
+    backend: probeBackend(),
+    masked_pat: maskedDisplay(existing)
+  });
+  return true;
+}
+async function listOrgsWithStoredPat() {
+  const seen = /* @__PURE__ */ new Set();
+  for (const ev of readAuditEvents()) {
+    if (ev.event === "auth.store") {
+      seen.add(ev.org);
+    } else if (ev.event === "auth.delete") {
+      seen.delete(ev.org);
+    }
+  }
+  const present = [];
+  for (const org of seen) {
+    const entry = new Entry(SERVICE, accountFor(org));
+    const value = wrapUnavailable(() => entry.getPassword());
+    if (value !== null) {
+      present.push(org);
+    }
+  }
+  present.sort((a, b) => a.localeCompare(b));
+  return present;
+}
+
+// src/services/auth.ts
+var PAT_PROMPT = "Enter your Azure DevOps PAT: ";
 async function promptForPat() {
   if (!process.stdin.isTTY) {
     return null;
@@ -419,7 +695,6 @@ async function promptForPat() {
       input: process.stdin,
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       output: null
-      // null disables readline's automatic echo
     });
     process.stderr.write(PAT_PROMPT);
     process.stdin.setRawMode(true);
@@ -475,12 +750,12 @@ function findDotEnvPat(startDir = process.cwd()) {
   }
   return null;
 }
-async function resolvePat(promptFn = promptForPat) {
+async function resolvePat(org) {
   const envPat = process.env.AZDO_PAT;
-  if (envPat) {
+  if (envPat && envPat.length > 0) {
     return { pat: envPat, source: "env" };
   }
-  const storedPat = await getPat();
+  const storedPat = await getPat(org);
   if (storedPat !== null) {
     return { pat: storedPat, source: "credential-store" };
   }
@@ -488,21 +763,34 @@ async function resolvePat(promptFn = promptForPat) {
   if (dotEnvPat !== null) {
     return { pat: dotEnvPat, source: "env" };
   }
-  const promptedPat = await promptFn();
-  if (promptedPat !== null) {
-    const normalizedPat = normalizePat(promptedPat);
-    if (normalizedPat !== null) {
-      const saved = await storePat(normalizedPat);
-      if (!saved) {
-        process.stderr.write("Warning: Could not save PAT to credential store. You may need to enter it again next time.\n");
-      }
-      return { pat: normalizedPat, source: "prompt" };
-    }
+  return null;
+}
+async function requirePat(org) {
+  const cred = await resolvePat(org);
+  if (cred !== null) {
+    return cred;
   }
   throw new Error(
-    "Authentication cancelled. Set AZDO_PAT environment variable or run again to enter a PAT."
+    `No PAT available for org "${org}". Set AZDO_PAT environment variable or run \`azdo auth --org ${org}\`.`
   );
 }
+async function validatePatAgainstAzdo(pat, org) {
+  const url = `https://dev.azure.com/${encodeURIComponent(org)}/_apis/projects?$top=1&api-version=7.1`;
+  const auth = Buffer.from(`:${pat}`).toString("base64");
+  const response = await fetch(url, {
+    headers: {
+      Authorization: `Basic ${auth}`,
+      Accept: "application/json"
+    }
+  });
+  if (response.status === 200) {
+    return { ok: true, status: 200 };
+  }
+  if (response.status === 401 || response.status === 403) {
+    return { ok: false, status: response.status };
+  }
+  throw new Error(`Azure DevOps returned HTTP ${response.status} while validating PAT for org "${org}".`);
+}
 
 // src/services/git-remote.ts
 import { execSync } from "child_process";
@@ -574,122 +862,57 @@ function getCurrentBranch() {
   return branch;
 }
 
-// src/services/config-store.ts
-import fs from "fs";
-import path from "path";
-import os from "os";
-var SETTINGS = [
-  {
-    key: "org",
-    description: "Azure DevOps organization name",
-    type: "string",
-    example: "mycompany",
-    required: true
-  },
-  {
-    key: "project",
-    description: "Azure DevOps project name",
-    type: "string",
-    example: "MyProject",
-    required: true
-  },
-  {
-    key: "fields",
-    description: "Extra work item fields to include (comma-separated reference names)",
-    type: "string[]",
-    example: "System.Tags,Custom.Priority",
-    required: false
-  },
-  {
-    key: "markdown",
-    description: "Convert rich text fields to markdown on display",
-    type: "boolean",
-    example: "true",
-    required: false
-  }
-];
-var VALID_KEYS = SETTINGS.map((s) => s.key);
-function getConfigPath() {
-  return path.join(os.homedir(), ".azdo", "config.json");
-}
-function loadConfig() {
-  const configPath = getConfigPath();
-  let raw;
+// src/services/org-resolver.ts
+function defaultDetectFromGit() {
   try {
-    raw = fs.readFileSync(configPath, "utf-8");
-  } catch (err) {
-    if (err.code === "ENOENT") {
-      return {};
-    }
-    throw err;
-  }
-  try {
-    return JSON.parse(raw);
+    return detectAzdoContext().org ?? null;
   } catch {
-    process.stderr.write(`Warning: Config file ${configPath} contains invalid JSON. Using defaults.
-`);
-    return {};
+    return null;
   }
 }
-function saveConfig(config) {
-  const configPath = getConfigPath();
-  const dir = path.dirname(configPath);
-  fs.mkdirSync(dir, { recursive: true });
-  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+function defaultReadConfig() {
+  return loadConfig();
 }
-function validateKey(key) {
-  if (!VALID_KEYS.includes(key)) {
-    throw new Error(`Unknown setting key "${key}". Valid keys: ${VALID_KEYS.join(", ")}`);
+function resolveOrg(options) {
+  if (options.org && options.org.length > 0) {
+    return { org: options.org, source: "flag" };
   }
-}
-function getConfigValue(key) {
-  validateKey(key);
-  const config = loadConfig();
-  return config[key];
-}
-function setConfigValue(key, value) {
-  validateKey(key);
-  const config = loadConfig();
-  if (value === "") {
-    delete config[key];
-  } else if (key === "markdown") {
-    if (value !== "true" && value !== "false") {
-      throw new Error(`Invalid value "${value}" for markdown. Must be "true" or "false".`);
-    }
-    config.markdown = value === "true";
-  } else if (key === "fields") {
-    config.fields = value.split(",").map((s) => s.trim());
-  } else {
-    config[key] = value;
+  const gitOrg = (options.detectFromGit ?? defaultDetectFromGit)();
+  if (gitOrg && gitOrg.length > 0) {
+    return { org: gitOrg, source: "git" };
   }
-  saveConfig(config);
+  const configOrg = (options.readConfig ?? defaultReadConfig)().org;
+  if (configOrg && configOrg.length > 0) {
+    return { org: configOrg, source: "config" };
+  }
+  return null;
 }
-function unsetConfigValue(key) {
-  validateKey(key);
-  const config = loadConfig();
-  delete config[key];
-  saveConfig(config);
+function formatResolutionError() {
+  return [
+    "Could not resolve an Azure DevOps organization. Options (in priority order):",
+    "  1. Pass --org <name> on the command line.",
+    "  2. Run this command from a git repo whose origin remote is an Azure DevOps URL.",
+    "  3. Run `azdo config set org <name>` once to set a persistent default."
+  ].join("\n");
 }
 
 // src/services/context.ts
 function resolveContext(options) {
-  if (options.org && options.project) {
-    return { org: options.org, project: options.project };
-  }
-  const config = loadConfig();
-  if (config.org && config.project) {
-    return { org: config.org, project: config.project };
-  }
+  const resolvedOrg = resolveOrg({ org: options.org });
   let gitContext = null;
   try {
     gitContext = detectAzdoContext();
   } catch {
   }
-  const org = config.org || gitContext?.org;
-  const project = config.project || gitContext?.project;
+  const config = loadConfig();
+  const org = resolvedOrg?.org;
+  const project = options.project || (gitContext?.project && gitContext.project.length > 0 ? gitContext.project : void 0) || config.project;
   if (org && project) {
     return { org, project };
   }
+  if (!org) {
+    throw new Error(formatResolutionError());
+  }
   throw new Error(
     'Could not determine org/project. Use --org and --project flags, work from an Azure DevOps git repo, or run "azdo config set org/project".'
   );
@@ -965,7 +1188,7 @@ function createGetItemCommand() {
       let context;
       try {
         context = resolveContext(options);
-        const credential = await resolvePat();
+        const credential = await requirePat(context.org);
         const fieldsList = options.fields === void 0 ? parseRequestedFields(loadConfig().fields) : parseRequestedFields(options.fields);
         const workItem = await getWorkItem(context, id, credential.pat, fieldsList);
         const markdownEnabled = options.markdown ?? loadConfig().markdown ?? false;
@@ -983,19 +1206,318 @@ function createGetItemCommand() {
 import { Command as Command2 } from "commander";
 function createClearPatCommand() {
   const command = new Command2("clear-pat");
-  command.description("Remove the stored Azure DevOps PAT from the credential store").action(async () => {
-    const deleted = await deletePat();
+  command.description("Remove a stored Azure DevOps PAT (deprecated: use `azdo auth logout`)").option("--org <name>", "Azure DevOps organization (overrides auto-detect / config)").action(async (options) => {
+    process.stderr.write("`azdo clear-pat` is deprecated; use `azdo auth logout [--org <name>]` instead.\n");
+    const resolved = resolveOrg({ org: options.org });
+    if (!resolved) {
+      process.stderr.write(`${formatResolutionError()}
+`);
+      process.exitCode = 3;
+      return;
+    }
+    const deleted = await deletePat(resolved.org);
     if (deleted) {
-      process.stdout.write("PAT removed from credential store.\n");
+      process.stdout.write(`PAT removed for org ${resolved.org}.
+`);
     } else {
-      process.stdout.write("No stored PAT found.\n");
+      process.stdout.write(`No stored PAT found for org ${resolved.org}.
+`);
     }
   });
   return command;
 }
 
-// src/commands/config.ts
+// src/commands/auth.ts
 import { Command as Command3 } from "commander";
+
+// src/services/browser-open.ts
+import { execFile } from "child_process";
+function isHeadless(platform, hasDisplay) {
+  if (platform === "linux") {
+    return !hasDisplay;
+  }
+  return false;
+}
+function commandForPlatform(platform) {
+  switch (platform) {
+    case "darwin":
+      return { cmd: "open", args: (url) => [url] };
+    case "win32":
+      return { cmd: "cmd", args: (url) => ["/c", "start", '""', url] };
+    case "linux":
+      return { cmd: "xdg-open", args: (url) => [url] };
+    default:
+      return null;
+  }
+}
+async function openUrl(url, opts = {}) {
+  const platform = opts.platform ?? process.platform;
+  const hasDisplay = opts.hasDisplay ?? (process.env.DISPLAY !== void 0 && process.env.DISPLAY !== "");
+  const forcePrint = opts.forcePrint ?? false;
+  if (forcePrint || isHeadless(platform, hasDisplay)) {
+    process.stderr.write(`Open this URL in your browser: ${url}
+`);
+    return "printed";
+  }
+  const spec = commandForPlatform(platform);
+  if (!spec) {
+    process.stderr.write(`Open this URL in your browser: ${url}
+`);
+    return "printed";
+  }
+  const runner = opts.execFileFn ?? ((cmd, args, cb) => execFile(cmd, args, { timeout: 5e3 }, (err) => cb(err)));
+  return await new Promise((resolve2) => {
+    try {
+      runner(spec.cmd, spec.args(url), (err) => {
+        if (err) {
+          process.stderr.write(`Open this URL in your browser: ${url}
+`);
+          resolve2("printed");
+        } else {
+          resolve2("opened");
+        }
+      });
+    } catch {
+      process.stderr.write(`Open this URL in your browser: ${url}
+`);
+      resolve2("printed");
+    }
+  });
+}
+
+// src/commands/auth.ts
+async function readStdinToString() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+async function confirmOverwrite(org) {
+  if (!process.stdin.isTTY) return true;
+  process.stderr.write(`A PAT is already stored for org ${org}. Overwrite? [y/N] `);
+  return await new Promise((resolve2) => {
+    process.stdin.setEncoding("utf8");
+    let answered = false;
+    const handler = (data) => {
+      if (answered) return;
+      answered = true;
+      process.stdin.removeListener("data", handler);
+      process.stdin.pause();
+      const trimmed = data.trim().toLowerCase();
+      resolve2(trimmed === "y" || trimmed === "yes");
+    };
+    process.stdin.resume();
+    process.stdin.on("data", handler);
+  });
+}
+async function handleAuthRoot(options) {
+  const resolved = resolveOrg({ org: options.org });
+  if (!resolved) {
+    process.stderr.write(`${formatResolutionError()}
+`);
+    process.exitCode = 3;
+    return;
+  }
+  const org = resolved.org;
+  const wantBrowser = options.browser !== false && !options.fromStdin;
+  if (wantBrowser) {
+    const url = `https://dev.azure.com/${encodeURIComponent(org)}/_usersSettings/tokens`;
+    await openUrl(url);
+  }
+  const raw = options.fromStdin ? await readStdinToString() : await promptForPat();
+  const pat = raw ? normalizePat(raw) : null;
+  if (!pat) {
+    process.stderr.write("No PAT provided. Aborting.\n");
+    process.exitCode = 1;
+    return;
+  }
+  let validation;
+  try {
+    validation = await validatePatAgainstAzdo(pat, org);
+  } catch (err) {
+    process.stderr.write(`Could not reach Azure DevOps to validate PAT: ${err.message}
+`);
+    process.exitCode = 1;
+    return;
+  }
+  if (!validation.ok) {
+    appendAuthAuditEvent({ event: "auth.validate.fail", org, backend: probeBackend() });
+    process.stderr.write(`PAT validation failed (HTTP ${validation.status}). Token NOT stored.
+`);
+    process.exitCode = 2;
+    return;
+  }
+  appendAuthAuditEvent({
+    event: "auth.validate.ok",
+    org,
+    backend: probeBackend(),
+    masked_pat: maskedDisplay(pat)
+  });
+  try {
+    const existing = await getPat(org);
+    if (existing !== null) {
+      const overwrite = await confirmOverwrite(org);
+      if (!overwrite) {
+        process.stderr.write("Aborted. Existing PAT preserved.\n");
+        process.exitCode = 1;
+        return;
+      }
+    }
+    await storePat(org, pat);
+  } catch (err) {
+    if (err instanceof CredentialStoreUnavailableError) {
+      process.stderr.write(`${err.message}
+`);
+      process.exitCode = 4;
+      return;
+    }
+    throw err;
+  }
+  process.stdout.write(`PAT stored for org ${org} in ${probeBackend()}.
+`);
+}
+async function handleStatus(options, org) {
+  let backend;
+  let value;
+  try {
+    backend = probeBackend();
+    value = await getPat(org);
+  } catch (err) {
+    if (err instanceof CredentialStoreUnavailableError) {
+      process.stderr.write(`${err.message}
+`);
+      process.exitCode = 4;
+      return;
+    }
+    throw err;
+  }
+  const storedEvents = readAuditEvents().filter((ev) => ev.org === org && ev.event === "auth.store");
+  const last = storedEvents[storedEvents.length - 1];
+  const updatedAt = last?.ts ?? null;
+  if (!value) {
+    if (options.json) {
+      process.stdout.write(
+        `${JSON.stringify({ org, backend, stored: false, masked: null, updated_at: updatedAt })}
+`
+      );
+    } else {
+      process.stdout.write(`Organization: ${org}
+Backend:      ${backend}
+Stored:       no
+`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+  const masked = maskedDisplay(value);
+  if (options.json) {
+    process.stdout.write(
+      `${JSON.stringify({ org, backend, stored: true, masked, updated_at: updatedAt })}
+`
+    );
+  } else {
+    process.stdout.write(
+      `Organization: ${org}
+Backend:      ${backend}
+Stored:       yes
+Identifier:   ${masked}
+` + (updatedAt ? `Last updated: ${updatedAt}
+` : "")
+    );
+  }
+}
+async function handleLogout(options, orgFromGlobal) {
+  if (options.all && orgFromGlobal) {
+    process.stderr.write("--org and --all are mutually exclusive.\n");
+    process.exitCode = 1;
+    return;
+  }
+  if (options.all) {
+    let orgs;
+    try {
+      orgs = await listOrgsWithStoredPat();
+    } catch (err) {
+      if (err instanceof CredentialStoreUnavailableError) {
+        process.stderr.write(`${err.message}
+`);
+        process.exitCode = 4;
+        return;
+      }
+      throw err;
+    }
+    if (orgs.length === 0) {
+      process.stdout.write("No stored PATs to remove.\n");
+      return;
+    }
+    for (const org of orgs) {
+      try {
+        await deletePat(org);
+        process.stdout.write(`PAT removed for org ${org}.
+`);
+      } catch (err) {
+        process.stderr.write(`Failed to remove PAT for org ${org}: ${err.message}
+`);
+        process.exitCode = 1;
+      }
+    }
+    return;
+  }
+  const resolved = resolveOrg({ org: orgFromGlobal });
+  if (!resolved) {
+    process.stderr.write(`${formatResolutionError()}
+`);
+    process.exitCode = 3;
+    return;
+  }
+  try {
+    const removed = await deletePat(resolved.org);
+    if (removed) {
+      process.stdout.write(`PAT removed for org ${resolved.org}.
+`);
+    } else {
+      process.stdout.write(`No stored PAT found for org ${resolved.org}.
+`);
+    }
+  } catch (err) {
+    if (err instanceof CredentialStoreUnavailableError) {
+      process.stderr.write(`${err.message}
+`);
+      process.exitCode = 4;
+      return;
+    }
+    throw err;
+  }
+}
+function createAuthCommand() {
+  const command = new Command3("auth");
+  command.description("Manage Azure DevOps Personal Access Tokens (PAT) in the OS secret vault");
+  command.option("--org <name>", "Azure DevOps organization (flag wins over auto-detect / config)").option("--from-stdin", "read PAT from stdin instead of prompting", false).option("--no-browser", "do not open the Azure DevOps PAT page in a browser");
+  command.action(async (options) => {
+    await handleAuthRoot(options);
+  });
+  const statusCmd = command.command("status").description("Report whether a PAT is stored for the resolved org (masked, never the full value)").option("--json", "emit a JSON object", false);
+  statusCmd.action(async (options) => {
+    const globals = statusCmd.optsWithGlobals();
+    const resolved = resolveOrg({ org: globals.org });
+    if (!resolved) {
+      process.stderr.write(`${formatResolutionError()}
+`);
+      process.exitCode = 3;
+      return;
+    }
+    await handleStatus(options, resolved.org);
+  });
+  const logoutCmd = command.command("logout").description("Remove the stored PAT for an org (or all orgs with --all)").option("--all", "remove the stored PAT for every org", false);
+  logoutCmd.action(async (options) => {
+    const globals = logoutCmd.optsWithGlobals();
+    await handleLogout(options, globals.org);
+  });
+  return command;
+}
+
+// src/commands/config.ts
+import { Command as Command4 } from "commander";
 import { createInterface as createInterface2 } from "readline";
 function formatConfigValue(value, unsetFallback = "") {
   if (value === void 0) {
@@ -1055,9 +1577,9 @@ async function promptForSetting(cfg, setting, ask) {
 `);
 }
 function createConfigCommand() {
-  const config = new Command3("config");
+  const config = new Command4("config");
   config.description("Manage CLI settings");
-  const set = new Command3("set");
+  const set = new Command4("set");
   set.description("Set a configuration value").argument("<key>", "setting key (org, project, fields)").argument("<value>", "setting value").option("--json", "output in JSON format").action((key, value, options) => {
     try {
       setConfigValue(key, value);
@@ -1078,7 +1600,7 @@ function createConfigCommand() {
       process.exit(1);
     }
   });
-  const get = new Command3("get");
+  const get = new Command4("get");
   get.description("Get a configuration value").argument("<key>", "setting key (org, project, fields)").option("--json", "output in JSON format").action((key, options) => {
     try {
       const value = getConfigValue(key);
@@ -1101,7 +1623,7 @@ function createConfigCommand() {
       process.exit(1);
     }
   });
-  const list = new Command3("list");
+  const list = new Command4("list");
   list.description("List all configuration values").option("--json", "output in JSON format").action((options) => {
     const cfg = loadConfig();
     if (options.json) {
@@ -1110,7 +1632,7 @@ function createConfigCommand() {
     }
     writeConfigList(cfg);
   });
-  const unset = new Command3("unset");
+  const unset = new Command4("unset");
   unset.description("Remove a configuration value").argument("<key>", "setting key (org, project, fields)").option("--json", "output in JSON format").action((key, options) => {
     try {
       unsetConfigValue(key);
@@ -1127,7 +1649,7 @@ function createConfigCommand() {
       process.exit(1);
     }
   });
-  const wizard = new Command3("wizard");
+  const wizard = new Command4("wizard");
   wizard.description("Interactive wizard to configure all settings").action(async () => {
     if (!process.stdin.isTTY) {
       process.stderr.write(
@@ -1158,9 +1680,9 @@ function createConfigCommand() {
 }
 
 // src/commands/set-state.ts
-import { Command as Command4 } from "commander";
+import { Command as Command5 } from "commander";
 function createSetStateCommand() {
-  const command = new Command4("set-state");
+  const command = new Command5("set-state");
   command.description("Change the state of a work item").argument("<id>", "work item ID").argument("<state>", 'target state (e.g., "Active", "Closed")').option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--json", "output result as JSON").action(
     async (idStr, state, options) => {
       const id = parseWorkItemId(idStr);
@@ -1168,7 +1690,7 @@ function createSetStateCommand() {
       let context;
       try {
         context = resolveContext(options);
-        const credential = await resolvePat();
+        const credential = await requirePat(context.org);
         const operations = [
           { op: "add", path: "/fields/System.State", value: state }
         ];
@@ -1196,9 +1718,9 @@ function createSetStateCommand() {
 }
 
 // src/commands/assign.ts
-import { Command as Command5 } from "commander";
+import { Command as Command6 } from "commander";
 function createAssignCommand() {
-  const command = new Command5("assign");
+  const command = new Command6("assign");
   command.description("Assign a work item to a user, or unassign it").argument("<id>", "work item ID").argument("[name]", "user display name or email").option("--unassign", "clear the Assigned To field").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--json", "output result as JSON").action(
     async (idStr, name, options) => {
       const id = parseWorkItemId(idStr);
@@ -1218,7 +1740,7 @@ function createAssignCommand() {
       let context;
       try {
         context = resolveContext(options);
-        const credential = await resolvePat();
+        const credential = await requirePat(context.org);
         const value = options.unassign ? "" : name;
         const operations = [
           { op: "add", path: "/fields/System.AssignedTo", value }
@@ -1248,9 +1770,9 @@ function createAssignCommand() {
 }
 
 // src/commands/set-field.ts
-import { Command as Command6 } from "commander";
+import { Command as Command7 } from "commander";
 function createSetFieldCommand() {
-  const command = new Command6("set-field");
+  const command = new Command7("set-field");
   command.description("Set any work item field by its reference name").argument("<id>", "work item ID").argument("<field>", "field reference name (e.g., System.Title)").argument("<value>", "new value for the field").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--json", "output result as JSON").action(
     async (idStr, field, value, options) => {
       const id = parseWorkItemId(idStr);
@@ -1258,7 +1780,7 @@ function createSetFieldCommand() {
       let context;
       try {
         context = resolveContext(options);
-        const credential = await resolvePat();
+        const credential = await requirePat(context.org);
         const operations = [
           { op: "add", path: `/fields/${field}`, value }
         ];
@@ -1286,9 +1808,9 @@ function createSetFieldCommand() {
 }
 
 // src/commands/get-md-field.ts
-import { Command as Command7 } from "commander";
+import { Command as Command8 } from "commander";
 function createGetMdFieldCommand() {
-  const command = new Command7("get-md-field");
+  const command = new Command8("get-md-field");
   command.description("Get a work item field value, converting HTML to markdown").argument("<id>", "work item ID").argument("<field>", "field reference name (e.g., System.Description)").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").action(
     async (idStr, field, options) => {
       const id = parseWorkItemId(idStr);
@@ -1296,7 +1818,7 @@ function createGetMdFieldCommand() {
       let context;
       try {
         context = resolveContext(options);
-        const credential = await resolvePat();
+        const credential = await requirePat(context.org);
         const value = await getWorkItemFieldValue(context, id, credential.pat, field);
         if (value === null) {
           process.stdout.write("\n");
@@ -1313,7 +1835,7 @@ function createGetMdFieldCommand() {
 
 // src/commands/set-md-field.ts
 import { existsSync as existsSync2, readFileSync as readFileSync3 } from "fs";
-import { Command as Command8 } from "commander";
+import { Command as Command9 } from "commander";
 function fail(message) {
   process.stderr.write(`Error: ${message}
 `);
@@ -1375,7 +1897,7 @@ function formatOutput(result, options, field) {
   }
 }
 function createSetMdFieldCommand() {
-  const command = new Command8("set-md-field");
+  const command = new Command9("set-md-field");
   command.description("Set a work item field with markdown content").argument("<id>", "work item ID").argument("<field>", "field reference name (e.g., System.Description)").argument("[content]", "markdown content to set").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--json", "output result as JSON").option("--file <path>", "read markdown content from file").action(
     async (idStr, field, inlineContent, options) => {
       const id = parseWorkItemId(idStr);
@@ -1384,7 +1906,7 @@ function createSetMdFieldCommand() {
       let context;
       try {
         context = resolveContext(options);
-        const credential = await resolvePat();
+        const credential = await requirePat(context.org);
         const operations = [
           { op: "add", path: `/fields/${field}`, value: content },
           { op: "add", path: `/multilineFieldsFormat/${field}`, value: "Markdown" }
@@ -1401,7 +1923,7 @@ function createSetMdFieldCommand() {
 
 // src/commands/upsert.ts
 import { existsSync as existsSync3, readFileSync as readFileSync4, unlinkSync } from "fs";
-import { Command as Command9 } from "commander";
+import { Command as Command10 } from "commander";
 
 // src/services/task-document.ts
 var FIELD_ALIASES = /* @__PURE__ */ new Map([
@@ -1685,7 +2207,7 @@ function handleUpsertError(err, id, context) {
   process.exit(1);
 }
 function createUpsertCommand() {
-  const command = new Command9("upsert");
+  const command = new Command10("upsert");
   command.description("Create or update a work item from a markdown document").argument("[id]", "work item ID to update; omit to create a new work item").option("--content <markdown>", "task document content").option("--file <path>", "read task document from file").option("--type <workItemType>", "create mode work item type (defaults to Task)").option("--json", "output result as JSON").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").action(async (idStr, options) => {
     validateOrgProjectPair(options);
     const id = idStr === void 0 ? void 0 : parseWorkItemId(idStr);
@@ -1700,7 +2222,7 @@ function createUpsertCommand() {
         ensureTitleForCreate(document.fields);
       }
       const operations = toPatchOperations(document.fields, action);
-      const credential = await resolvePat();
+      const credential = await requirePat(context.org);
       let writeResult;
       if (action === "created") {
         writeResult = await createWorkItem(context, createType, credential.pat, operations);
@@ -1726,7 +2248,7 @@ function createUpsertCommand() {
 }
 
 // src/commands/list-fields.ts
-import { Command as Command10 } from "commander";
+import { Command as Command11 } from "commander";
 function stringifyValue(value) {
   if (value === null || value === void 0) return "";
   if (typeof value === "object") return JSON.stringify(value);
@@ -1758,7 +2280,7 @@ function formatFieldList(fields) {
   }).join("\n");
 }
 function createListFieldsCommand() {
-  const command = new Command10("list-fields");
+  const command = new Command11("list-fields");
   command.description("List all fields of an Azure DevOps work item").argument("<id>", "work item ID").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--json", "output result as JSON").action(
     async (idStr, options) => {
       const id = parseWorkItemId(idStr);
@@ -1766,7 +2288,7 @@ function createListFieldsCommand() {
       let context;
       try {
         context = resolveContext(options);
-        const credential = await resolvePat();
+        const credential = await requirePat(context.org);
         const fields = await getWorkItemFields(context, id, credential.pat);
         if (options.json) {
           process.stdout.write(JSON.stringify({ id, fields }, null, 2) + "\n");
@@ -1785,7 +2307,7 @@ function createListFieldsCommand() {
 }
 
 // src/commands/pr.ts
-import { Command as Command11 } from "commander";
+import { Command as Command12 } from "commander";
 
 // src/services/pr-client.ts
 function buildPullRequestsUrl(context, repo, sourceBranch, opts) {
@@ -2015,7 +2537,7 @@ async function resolvePrCommandContext(options) {
   const context = resolveContext(options);
   const repo = detectRepoName();
   const branch = getCurrentBranch();
-  const credential = await resolvePat();
+  const credential = await requirePat(context.org);
   return {
     context,
     repo,
@@ -2024,7 +2546,7 @@ async function resolvePrCommandContext(options) {
   };
 }
 function createPrStatusCommand() {
-  const command = new Command11("status");
+  const command = new Command12("status");
   command.description("Check pull requests for the current branch").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--json", "output JSON").action(async (options) => {
     validateOrgProjectPair(options);
     let context;
@@ -2059,7 +2581,7 @@ function createPrStatusCommand() {
   return command;
 }
 function createPrOpenCommand() {
-  const command = new Command11("open");
+  const command = new Command12("open");
   command.description("Open a pull request from the current branch to develop").option("--title <title>", "pull request title").option("--description <description>", "pull request description").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--json", "output JSON").action(async (options) => {
     validateOrgProjectPair(options);
     const title = options.title?.trim();
@@ -2112,7 +2634,7 @@ ${result.pullRequest.url}
   return command;
 }
 function createPrCommentsCommand() {
-  const command = new Command11("comments");
+  const command = new Command12("comments");
   command.description("List active pull request comments for the current branch").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--json", "output JSON").action(async (options) => {
     validateOrgProjectPair(options);
     let context;
@@ -2151,7 +2673,7 @@ function createPrCommentsCommand() {
   return command;
 }
 function createPrCommand() {
-  const command = new Command11("pr");
+  const command = new Command12("pr");
   command.description("Manage Azure DevOps pull requests");
   command.addCommand(createPrStatusCommand());
   command.addCommand(createPrOpenCommand());
@@ -2160,7 +2682,7 @@ function createPrCommand() {
 }
 
 // src/commands/comments.ts
-import { Command as Command12 } from "commander";
+import { Command as Command13 } from "commander";
 function writeError2(message) {
   process.stderr.write(`Error: ${message}
 `);
@@ -2180,14 +2702,14 @@ function formatComments(result, convertMarkdown) {
   return lines.join("\n");
 }
 function createCommentsListCommand() {
-  const command = new Command12("list");
+  const command = new Command13("list");
   command.description("List visible comments for a work item").argument("<id>", "work item ID").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--json", "output JSON").option("--markdown", "convert HTML comment bodies to markdown").action(async (idStr, options) => {
     validateOrgProjectPair(options);
     const id = parseWorkItemId(idStr);
     let context;
     try {
       context = resolveContext(options);
-      const credential = await resolvePat();
+      const credential = await requirePat(context.org);
       const result = await listWorkItemComments(context, id, credential.pat);
       if (options.json) {
         process.stdout.write(`${JSON.stringify(result, null, 2)}
@@ -2208,7 +2730,7 @@ function createCommentsListCommand() {
   return command;
 }
 function createCommentsAddCommand() {
-  const command = new Command12("add");
+  const command = new Command13("add");
   command.description("Add a comment to a work item").argument("<id>", "work item ID").argument("<text>", "comment text").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--json", "output JSON").option("--markdown", "post comment as markdown").action(async (idStr, text, options) => {
     validateOrgProjectPair(options);
     const id = parseWorkItemId(idStr);
@@ -2218,7 +2740,7 @@ function createCommentsAddCommand() {
     let context;
     try {
       context = resolveContext(options);
-      const credential = await resolvePat();
+      const credential = await requirePat(context.org);
       const format = options.markdown === true ? "markdown" : "html";
       const result = await addWorkItemComment(context, id, credential.pat, text, format);
       if (options.json) {
@@ -2235,7 +2757,7 @@ function createCommentsAddCommand() {
   return command;
 }
 function createCommentsCommand() {
-  const command = new Command12("comments");
+  const command = new Command13("comments");
   command.description("Manage Azure DevOps work item comments");
   command.addCommand(createCommentsListCommand());
   command.addCommand(createCommentsAddCommand());
@@ -2243,12 +2765,12 @@ function createCommentsCommand() {
 }
 
 // src/commands/download-attachment.ts
-import { Command as Command13 } from "commander";
+import { Command as Command14 } from "commander";
 import { writeFile } from "fs/promises";
 import { existsSync as existsSync4 } from "fs";
 import { join as join2 } from "path";
 function createDownloadAttachmentCommand() {
-  const command = new Command13("download-attachment");
+  const command = new Command14("download-attachment");
   command.description("Download an attachment from an Azure DevOps work item").argument("<id>", "work item ID").argument("<filename>", "name of the attachment to download").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--output <dir>", "target directory for the downloaded file").action(
     async (idStr, filename, options) => {
       const id = parseWorkItemId(idStr);
@@ -2256,7 +2778,7 @@ function createDownloadAttachmentCommand() {
       let context;
       try {
         context = resolveContext(options);
-        const credential = await resolvePat();
+        const credential = await requirePat(context.org);
         const outputDir = options.output ?? ".";
         if (!existsSync4(outputDir)) {
           process.stderr.write(`Error: Output directory "${outputDir}" does not exist.
@@ -2290,9 +2812,10 @@ function createDownloadAttachmentCommand() {
 }
 
 // src/index.ts
-var program = new Command14();
+var program = new Command15();
 program.name("azdo").description("Azure DevOps CLI tool").version(version, "-v, --version");
 program.addCommand(createGetItemCommand());
+program.addCommand(createAuthCommand());
 program.addCommand(createClearPatCommand());
 program.addCommand(createConfigCommand());
 program.addCommand(createSetStateCommand());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "azdo-cli",
-  "version": "0.10.0-develop.213",
+  "version": "0.10.0-develop.233",
   "description": "Azure DevOps CLI tool",
   "type": "module",
   "bin": {