azdo-cli 0.5.0-030-auth-diagnostics.530 → 0.5.0-030-auth-diagnostics.537

package/README.md

@@ -17,7 +17,8 @@ Azure DevOps CLI focused on work item read/write workflows.
 - Check branch pull request status, open PRs to `develop`, list PR comment threads for any PR (`--pr-number`), and resolve/reopen threads from the CLI (`pr`)
 - Persist org/project/default fields in local config (`config`)
 - List all fields of a work item (`list-fields`)
-- Authenticate per Azure DevOps organization with `azdo auth login` — OAuth (Microsoft Entra) by default, or a Personal Access Token via `--use-pat` (or the `AZDO_PAT` env var). Credentials are stored in the OS credential store. Inspect with `azdo auth status`, remove with `azdo auth logout`. See [docs/authentication.md](docs/authentication.md).
+- Authenticate per Azure DevOps organization with `azdo auth login` — OAuth (Microsoft Entra) by default, or a Personal Access Token via `--use-pat` (or the `AZDO_PAT` env var). Credentials are stored in the OS credential store. Inspect with `azdo auth status`, remove with `azdo auth logout`. Diagnose auth problems with `azdo auth diagnose`. See [docs/authentication.md](docs/authentication.md).
+- Trace all HTTP requests to a local file with `--trace <filepath>` (sensitive headers and tokens are automatically redacted).
 
 ## Installation
 

package/dist/index.js

@@ -51,6 +51,78 @@ var version = pkg.version;
 // src/commands/get-item.ts
 import { Command } from "commander";
 
+// src/services/trace-writer.ts
+import { openSync, writeSync, closeSync } from "fs";
+import { platform } from "os";
+var REDACTED = "[REDACTED]";
+var SENSITIVE_HEADER = /^(authorization|x-.*token)$/i;
+var SENSITIVE_QUERY_PARAM = /^(token|pat)$/i;
+var SENSITIVE_BODY_FIELD = /^(token|accessToken|pat)$/;
+function redactHeaders(headers) {
+  const out = {};
+  for (const [key, value] of Object.entries(headers)) {
+    out[key] = SENSITIVE_HEADER.test(key) ? REDACTED : value;
+  }
+  return out;
+}
+function redactUrl(url) {
+  try {
+    const u = new URL(url);
+    for (const [key] of u.searchParams.entries()) {
+      if (SENSITIVE_QUERY_PARAM.test(key)) {
+        u.searchParams.set(key, REDACTED);
+      }
+    }
+    return u.toString();
+  } catch {
+    return url;
+  }
+}
+function redactBody(body) {
+  if (body === null) return null;
+  try {
+    const parsed = JSON.parse(body);
+    let changed = false;
+    const redacted = { ...parsed };
+    for (const key of Object.keys(parsed)) {
+      if (SENSITIVE_BODY_FIELD.test(key)) {
+        redacted[key] = REDACTED;
+        changed = true;
+      }
+    }
+    return changed ? JSON.stringify(redacted) : body;
+  } catch {
+    return body;
+  }
+}
+var TraceWriter = class {
+  fd;
+  constructor(filepath) {
+    const mode = platform() === "win32" ? void 0 : 384;
+    this.fd = openSync(filepath, "a", mode);
+  }
+  append(entry) {
+    const line = JSON.stringify(entry) + "\n\n";
+    writeSync(this.fd, line);
+  }
+  close() {
+    closeSync(this.fd);
+  }
+};
+var activeWriter = null;
+function initTraceWriter(filepath) {
+  try {
+    activeWriter = new TraceWriter(filepath);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`Warning: could not open trace file "${filepath}": ${msg}
+`);
+  }
+}
+function getActiveTraceWriter() {
+  return activeWriter;
+}
+
 // src/services/azdo-client.ts
 var DEFAULT_FIELDS = [
   "System.Title",
@@ -74,12 +146,48 @@ function authHeaders(credentialOrPat) {
   const token = Buffer.from(`:${credentialOrPat.pat}`).toString("base64");
   return { Authorization: `Basic ${token}` };
 }
+async function fetchRaw(url, init) {
+  let response;
+  try {
+    response = await fetch(url, init);
+  } catch (err) {
+    throw new Error(`NETWORK_ERROR: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+  }
+  const body = await response.text();
+  return { status: response.status, body };
+}
 async function fetchWithErrors(url, init) {
+  const writer = getActiveTraceWriter();
   let response;
   try {
     response = await fetch(url, init);
-  } catch {
-    throw new Error("NETWORK_ERROR");
+  } catch (err) {
+    throw new Error("NETWORK_ERROR", { cause: err });
+  }
+  if (writer) {
+    const reqHeaders = redactHeaders(init.headers ?? {});
+    const reqBody = typeof init.body === "string" ? redactBody(init.body) : null;
+    let responseBody = "";
+    const clone = response.clone();
+    try {
+      responseBody = await clone.text();
+    } catch {
+    }
+    const respHeaders = {};
+    response.headers.forEach((v, k) => {
+      respHeaders[k] = v;
+    });
+    const entry = {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      method: (init.method ?? "GET").toUpperCase(),
+      url: redactUrl(url),
+      requestHeaders: reqHeaders,
+      requestBody: reqBody ?? null,
+      responseStatus: response.status,
+      responseHeaders: respHeaders,
+      responseBody
+    };
+    writer.append(entry);
   }
   if (response.status === 401) throw new Error("AUTH_FAILED");
   if (response.status === 403) throw new Error("PERMISSION_DENIED");
@@ -1561,6 +1669,71 @@ function createClearPatCommand() {
 
 // src/commands/auth.ts
 import { Command as Command3 } from "commander";
+
+// src/services/auth-diagnostics.ts
+async function runConnectivityTest(org, cred) {
+  const url = `https://dev.azure.com/${encodeURIComponent(org)}/_apis/projects?api-version=7.1&$top=1`;
+  let result;
+  try {
+    result = await fetchRaw(url, { headers: authHeaders(cred) });
+  } catch (err) {
+    return { status: "failed", error: err instanceof Error ? err.message : String(err) };
+  }
+  if (result.status >= 200 && result.status < 300) {
+    return { status: "ok", error: null };
+  }
+  let error = `HTTP ${result.status}`;
+  try {
+    const parsed = JSON.parse(result.body);
+    if (typeof parsed.message === "string" && parsed.message.trim() !== "") {
+      error = parsed.message.trim();
+    }
+  } catch {
+  }
+  return { status: "failed", error };
+}
+async function diagnoseAuth(org, project, resolveCredential) {
+  const cred = await resolveCredential(org);
+  if (cred === null) {
+    return {
+      authType: "none",
+      credentialSource: null,
+      org,
+      project,
+      connectivityStatus: "no-credentials",
+      connectivityError: null
+    };
+  }
+  const connectivity = await runConnectivityTest(org, cred);
+  const sourceLabel = cred.source === "env" ? `env:${process.env.AZDO_PAT ? "AZDO_PAT" : "dotenv"}` : "credential-store";
+  return {
+    authType: cred.kind ?? "pat",
+    credentialSource: sourceLabel,
+    org,
+    project,
+    connectivityStatus: connectivity.status,
+    connectivityError: connectivity.error
+  };
+}
+function formatDiagnosticReport(report, json) {
+  if (json) {
+    return JSON.stringify(report, null, 2);
+  }
+  const connectivityLine = report.connectivityStatus === "ok" ? "OK" : report.connectivityStatus === "no-credentials" ? "no credentials found" : "FAILED";
+  const lines = [
+    `Auth type:    ${report.authType}`,
+    `Source:       ${report.credentialSource ?? "(none)"}`,
+    `Org:          ${report.org}`,
+    `Project:      ${report.project ?? "(not set)"}`,
+    `Connectivity: ${connectivityLine}`
+  ];
+  if (report.connectivityStatus === "failed" && report.connectivityError !== null) {
+    lines.push(`Error:        ${report.connectivityError}`);
+  }
+  return lines.join("\n");
+}
+
+// src/commands/auth.ts
 async function readStdinToString() {
   const chunks = [];
   for await (const chunk of process.stdin) {
@@ -1982,6 +2155,25 @@ Note: \`azdo auth\` (no subcommand) preserves the legacy PAT-prompt entry point;
     const globals = logoutCmd.optsWithGlobals();
     await handleLogout(options, globals.org);
   });
+  const diagnoseCmd = command.command("diagnose").description("Show auth type, credential source, org, and live connectivity test result").option("--org <name>", "Azure DevOps organization (overrides context resolution)").option("--project <name>", "Azure DevOps project (optional context)").option("--json", "emit JSON instead of human-readable text", false);
+  diagnoseCmd.action(async (options) => {
+    const globals = diagnoseCmd.optsWithGlobals();
+    const orgName = options.org ?? globals.org;
+    const resolved = resolveOrg({ org: orgName });
+    if (!resolved) {
+      process.stderr.write(`${formatResolutionError()}
+`);
+      process.exitCode = 1;
+      return;
+    }
+    const report = await diagnoseAuth(resolved.org, options.project ?? null, resolveAuthCredential);
+    const output = formatDiagnosticReport(report, options.json ?? false);
+    process.stdout.write(`${output}
+`);
+    if (report.connectivityStatus === "failed") {
+      process.exitCode = 1;
+    }
+  });
   return command;
 }
 
@@ -5203,6 +5395,7 @@ process.stderr.on("error", exitOnEpipe);
 var program = new Command17();
 program.name("azdo").description("Azure DevOps CLI tool").version(version, "-v, --version");
 program.option("--no-update-check", "Skip the check for a newer published version");
+program.option("--trace <filepath>", "Append redacted HTTP request/response trace to a file (owner-read-only permissions)");
 program.addCommand(createGetItemCommand());
 program.addCommand(createAuthCommand());
 program.addCommand(createClearPatCommand());
@@ -5220,6 +5413,12 @@ program.addCommand(createCommentsCommand());
 program.addCommand(createDownloadAttachmentCommand());
 program.addCommand(createRelationsCommand());
 program.showHelpAfterError();
+program.hook("preAction", () => {
+  const { trace } = program.opts();
+  if (trace) {
+    initTraceWriter(trace);
+  }
+});
 program.hook("postAction", async () => {
   const notice = await getUpdateNotice({ enabled: program.opts().updateCheck });
   if (notice) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "azdo-cli",
-  "version": "0.5.0-030-auth-diagnostics.530",
+  "version": "0.5.0-030-auth-diagnostics.537",
   "description": "Azure DevOps CLI tool",
   "type": "module",
   "bin": {