azdo-cli 0.10.0 → 0.11.0

package/dist/index.js

@@ -1,4 +1,34 @@
 #!/usr/bin/env node
+import {
+  AZDO_RESOURCE_ID,
+  CredentialMissingError,
+  CredentialStoreUnavailableError,
+  SETTINGS,
+  appendAuthAuditEvent,
+  buildScopeString,
+  defaultScopes,
+  deletePat,
+  firstPartyShippedScopes,
+  getConfigValue,
+  getPat,
+  getStoredCredential,
+  listOrgsWithStoredPat,
+  loadConfig,
+  maskedDisplay,
+  normalizePat,
+  openUrl,
+  probeBackend,
+  readAuditEvents,
+  readTokenResponse,
+  refreshIfNeeded,
+  resolveOAuthConfig,
+  runAuthCodeFlow,
+  setConfigValue,
+  storeOAuthCredential,
+  storePat,
+  tokenResponseToCredential,
+  unsetConfigValue
+} from "./chunk-C7RAZJHV.js";
 
 // src/index.ts
 import { Command as Command15 } from "commander";
@@ -26,8 +56,15 @@ var DEFAULT_FIELDS = [
   "System.AreaPath",
   "System.IterationPath"
 ];
-function authHeaders(pat) {
-  const token = Buffer.from(`:${pat}`).toString("base64");
+function authHeaders(credentialOrPat) {
+  if (typeof credentialOrPat === "string") {
+    const token2 = Buffer.from(`:${credentialOrPat}`).toString("base64");
+    return { Authorization: `Basic ${token2}` };
+  }
+  if (credentialOrPat.kind === "oauth") {
+    return { Authorization: `Bearer ${credentialOrPat.pat}` };
+  }
+  const token = Buffer.from(`:${credentialOrPat.pat}`).toString("base64");
   return { Authorization: `Basic ${token}` };
 }
 async function fetchWithErrors(url, init) {
@@ -48,6 +85,10 @@ async function fetchWithErrors(url, init) {
     }
     throw new Error(`NOT_FOUND${detail}`);
   }
+  const contentType = response.headers?.get("content-type") ?? "";
+  if (contentType.toLowerCase().startsWith("text/html")) {
+    throw new Error("AUTH_FAILED");
+  }
   return response;
 }
 async function readResponseMessage(response) {
@@ -90,9 +131,9 @@ function buildExtraFields(fields, requested) {
   }
   return Object.keys(result).length > 0 ? result : null;
 }
-function writeHeaders(pat) {
+function writeHeaders(cred) {
   return {
-    ...authHeaders(pat),
+    ...authHeaders(cred),
     "Content-Type": "application/json-patch+json"
   };
 }
@@ -147,13 +188,13 @@ async function readWriteResponse(response, errorCode) {
     fields: data.fields
   };
 }
-async function getWorkItemFields(context, id, pat) {
+async function getWorkItemFields(context, id, cred) {
   const url = new URL(
     `https://dev.azure.com/${encodeURIComponent(context.org)}/${encodeURIComponent(context.project)}/_apis/wit/workitems/${id}`
   );
   url.searchParams.set("api-version", "7.1");
   url.searchParams.set("$expand", "all");
-  const response = await fetchWithErrors(url.toString(), { headers: authHeaders(pat) });
+  const response = await fetchWithErrors(url.toString(), { headers: authHeaders(cred) });
   if (response.status === 400) {
     const serverMessage = await readResponseMessage(response);
     if (serverMessage) {
@@ -188,10 +229,10 @@ function buildWorkItemUrl(context, id, options = {}) {
   }
   return url;
 }
-async function fetchWorkItemResponse(context, id, pat, options = {}) {
+async function fetchWorkItemResponse(context, id, cred, options = {}) {
   const response = await fetchWithErrors(
     buildWorkItemUrl(context, id, options).toString(),
-    { headers: authHeaders(pat) }
+    { headers: authHeaders(cred) }
   );
   if (response.status === 400) {
     const serverMessage = await readResponseMessage(response);
@@ -204,12 +245,12 @@ async function fetchWorkItemResponse(context, id, pat, options = {}) {
   }
   return await response.json();
 }
-async function getWorkItem(context, id, pat, extraFields) {
+async function getWorkItem(context, id, cred, extraFields) {
   const normalizedExtraFields = extraFields ? normalizeFieldList(extraFields) : [];
-  const data = normalizedExtraFields.length > 0 ? await fetchWorkItemResponse(context, id, pat, {
+  const data = normalizedExtraFields.length > 0 ? await fetchWorkItemResponse(context, id, cred, {
     fields: normalizeFieldList([...DEFAULT_FIELDS, ...normalizedExtraFields])
-  }) : await fetchWorkItemResponse(context, id, pat, { includeRelations: true });
-  const relationsData = normalizedExtraFields.length > 0 ? await fetchWorkItemResponse(context, id, pat, { includeRelations: true }) : data;
+  }) : await fetchWorkItemResponse(context, id, cred, { includeRelations: true });
+  const relationsData = normalizedExtraFields.length > 0 ? await fetchWorkItemResponse(context, id, cred, { includeRelations: true }) : data;
   const descriptionParts = [];
   if (data.fields["System.Description"]) {
     descriptionParts.push({ label: "Description", value: data.fields["System.Description"] });
@@ -241,13 +282,13 @@ async function getWorkItem(context, id, pat, extraFields) {
     attachments: extractAttachments(relationsData.relations)
   };
 }
-async function getWorkItemFieldValue(context, id, pat, fieldName) {
+async function getWorkItemFieldValue(context, id, cred, fieldName) {
   const url = new URL(
     `https://dev.azure.com/${encodeURIComponent(context.org)}/${encodeURIComponent(context.project)}/_apis/wit/workitems/${id}`
   );
   url.searchParams.set("api-version", "7.1");
   url.searchParams.set("fields", fieldName);
-  const response = await fetchWithErrors(url.toString(), { headers: authHeaders(pat) });
+  const response = await fetchWithErrors(url.toString(), { headers: authHeaders(cred) });
   if (response.status === 400) {
     const serverMessage = await readResponseMessage(response);
     if (serverMessage) {
@@ -264,13 +305,13 @@ async function getWorkItemFieldValue(context, id, pat, fieldName) {
   }
   return stringifyFieldValue(value);
 }
-async function listWorkItemComments(context, id, pat) {
+async function listWorkItemComments(context, id, cred) {
   const comments = [];
   let continuationToken = null;
   do {
     const response = await fetchWithErrors(
       buildWorkItemCommentsListUrl(context, id, continuationToken ?? void 0).toString(),
-      { headers: authHeaders(pat) }
+      { headers: authHeaders(cred) }
     );
     if (!response.ok) {
       throw new Error(`HTTP_${response.status}`);
@@ -287,13 +328,13 @@ async function listWorkItemComments(context, id, pat) {
     comments
   };
 }
-async function addWorkItemComment(context, id, pat, text, format = "html") {
+async function addWorkItemComment(context, id, cred, text, format = "html") {
   const url = buildWorkItemCommentsUrl(context, id);
   url.searchParams.set("format", format);
   const response = await fetchWithErrors(url.toString(), {
     method: "POST",
     headers: {
-      ...authHeaders(pat),
+      ...authHeaders(cred),
       "Content-Type": "application/json"
     },
     body: JSON.stringify({ text })
@@ -315,8 +356,8 @@ async function addWorkItemComment(context, id, pat, text, format = "html") {
     url: data.url ?? null
   };
 }
-async function updateWorkItem(context, id, pat, fieldName, operations) {
-  const result = await applyWorkItemPatch(context, id, pat, operations);
+async function updateWorkItem(context, id, cred, fieldName, operations) {
+  const result = await applyWorkItemPatch(context, id, cred, operations);
   const title = result.fields["System.Title"];
   const lastOp = operations.at(-1);
   const fieldValue = lastOp?.value ?? null;
@@ -328,32 +369,32 @@ async function updateWorkItem(context, id, pat, fieldName, operations) {
     fieldValue
   };
 }
-async function createWorkItem(context, workItemType, pat, operations) {
+async function createWorkItem(context, workItemType, cred, operations) {
   const url = new URL(
     `https://dev.azure.com/${encodeURIComponent(context.org)}/${encodeURIComponent(context.project)}/_apis/wit/workitems/$${encodeURIComponent(workItemType)}`
   );
   url.searchParams.set("api-version", "7.1");
   const response = await fetchWithErrors(url.toString(), {
     method: "POST",
-    headers: writeHeaders(pat),
+    headers: writeHeaders(cred),
     body: JSON.stringify(operations)
   });
   return readWriteResponse(response, "CREATE_REJECTED");
 }
-async function applyWorkItemPatch(context, id, pat, operations) {
+async function applyWorkItemPatch(context, id, cred, operations) {
   const url = new URL(
     `https://dev.azure.com/${encodeURIComponent(context.org)}/${encodeURIComponent(context.project)}/_apis/wit/workitems/${id}`
   );
   url.searchParams.set("api-version", "7.1");
   const response = await fetchWithErrors(url.toString(), {
     method: "PATCH",
-    headers: writeHeaders(pat),
+    headers: writeHeaders(cred),
     body: JSON.stringify(operations)
   });
   return readWriteResponse(response, "UPDATE_REJECTED");
 }
-async function downloadAttachment(url, pat) {
-  const response = await fetchWithErrors(url, { headers: authHeaders(pat) });
+async function downloadAttachment(url, cred) {
+  const response = await fetchWithErrors(url, { headers: authHeaders(cred) });
   if (!response.ok) {
     throw new Error(`HTTP_${response.status}`);
   }
@@ -365,323 +406,124 @@ import { createInterface } from "readline";
 import { existsSync, readFileSync as readFileSync2 } from "fs";
 import { dirname as dirname2, join } from "path";
 
-// src/services/credential-store.ts
-import { Entry } from "@napi-rs/keyring";
-
-// 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;
+// src/services/oauth-device-code.ts
+var DeviceCodeFlowError = class extends Error {
+  reason;
+  constructor(reason, message, cause) {
+    super(message);
+    this.name = "DeviceCodeFlowError";
+    this.reason = reason;
     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 {
-    fs.chmodSync(dir, 448);
-  } catch {
-  }
-}
-function ensureFileWithPerms(file) {
-  if (!fs.existsSync(file)) {
-    fs.writeFileSync(file, "", { mode: 384 });
-    return;
-  }
+var MIN_INTERVAL_SEC = 5;
+async function defaultSleep(ms) {
+  await new Promise((r) => setTimeout(r, ms));
+}
+async function requestDeviceCode(oauthConfig, fetchFn) {
+  const body = new URLSearchParams({
+    client_id: oauthConfig.clientId,
+    scope: buildScopeString(oauthConfig.scopes)
+  });
+  const response = await fetchFn(oauthConfig.deviceCodeEndpoint, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+    body: body.toString()
+  });
+  const text = await response.text();
+  let parsed;
   try {
-    fs.chmodSync(file, 384);
+    parsed = JSON.parse(text);
   } catch {
+    throw new DeviceCodeFlowError("idp-error", `device-code endpoint returned non-JSON HTTP ${response.status}: ${text.slice(0, 200)}`);
   }
-}
-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
+  if (!response.ok) {
+    const err = parsed;
+    const code = err.error ?? "unknown";
+    const desc = err.error_description ? `: ${err.error_description}` : "";
+    throw new DeviceCodeFlowError(
+      "idp-error",
+      `device-code endpoint rejected request (${response.status}): ${code}${desc}`
+    );
   }
-];
-var VALID_KEYS = SETTINGS.map((s) => s.key);
-function getConfigPath() {
-  return path2.join(os2.homedir(), ".azdo", "config.json");
+  return parsed;
 }
-function loadConfig() {
-  const configPath = getConfigPath();
-  let raw;
-  try {
-    raw = fs2.readFileSync(configPath, "utf-8");
-  } catch (err) {
-    if (err.code === "ENOENT") {
-      return {};
-    }
-    throw err;
+async function classifyDeviceTokenResponse(response) {
+  if (response.ok) {
+    return { kind: "success", token: await readTokenResponse(response) };
   }
+  const text = await response.text();
+  let parsed;
   try {
-    return JSON.parse(raw);
+    parsed = JSON.parse(text);
   } catch {
-    process.stderr.write(`Warning: Config file ${configPath} contains invalid JSON. Using defaults.
-`);
-    return {};
+    throw new DeviceCodeFlowError("idp-error", `non-JSON HTTP ${response.status}: ${text.slice(0, 200)}`);
   }
-}
-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(", ")}`);
+  const errCode = parsed.error ?? "";
+  if (errCode === "authorization_pending") return { kind: "pending" };
+  if (errCode === "slow_down") return { kind: "slow_down" };
+  if (errCode === "expired_token") {
+    throw new DeviceCodeFlowError("expired_token", "device code expired before authorisation completed");
   }
-}
-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-masking.ts
-var VISIBLE_CHARS = 5;
-function maskedDisplay(pat) {
-  if (pat.length <= VISIBLE_CHARS * 2) {
-    return 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);
+  if (errCode === "access_denied") {
+    throw new DeviceCodeFlowError("access_denied", "authorisation denied by user");
   }
-}
-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'
+  const desc = parsed.error_description ? `: ${parsed.error_description}` : "";
+  throw new DeviceCodeFlowError(
+    "idp-error",
+    `IdP rejected device-token poll (${response.status}): ${errCode}${desc}`
   );
 }
-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();
-      }
+async function pollForDeviceToken(deviceCode, oauthConfig, initialIntervalSec, expiresAtMs, deps) {
+  const fetchFn = deps.fetch ?? fetch;
+  const now = deps.now ?? (() => Date.now());
+  const sleep = deps.sleep ?? defaultSleep;
+  let intervalSec = Math.max(MIN_INTERVAL_SEC, initialIntervalSec);
+  for (; ; ) {
+    if (now() >= expiresAtMs) {
+      throw new DeviceCodeFlowError("expired_token", "device-code flow expired before authorisation completed");
+    }
+    await sleep(intervalSec * 1e3);
+    const body = new URLSearchParams({
+      grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+      client_id: oauthConfig.clientId,
+      device_code: deviceCode
+    });
+    const response = await fetchFn(oauthConfig.tokenEndpoint, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+      body: body.toString()
+    });
+    const outcome = await classifyDeviceTokenResponse(response);
+    if (outcome.kind === "success") return outcome.token;
+    if (outcome.kind === "slow_down") {
+      intervalSec += 5;
     }
-    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 runDeviceCodeFlow(org, oauthConfig, deps = {}) {
+  const fetchFn = deps.fetch ?? fetch;
+  const now = deps.now ?? (() => Date.now());
+  const writePrompt = deps.writePrompt ?? ((m) => {
+    process.stderr.write(m);
   });
-}
-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;
+  const dc = await requestDeviceCode(oauthConfig, fetchFn);
+  const expiryMin = Math.round(dc.expires_in / 60);
+  writePrompt(
+    `
+To authenticate, open ${dc.verification_uri} in a browser and enter the code:
+
+    ${dc.user_code}
+
+Waiting for authorisation (expires in ${expiryMin} min)\u2026
+`
+  );
+  const expiresAtMs = now() + dc.expires_in * 1e3;
+  const token = await pollForDeviceToken(dc.device_code, oauthConfig, dc.interval, expiresAtMs, deps);
+  const credential = tokenResponseToCredential(org, oauthConfig, token, now());
+  return { credential, flowUsed: "device-code" };
 }
 
 // src/services/auth.ts
@@ -750,29 +592,36 @@ function findDotEnvPat(startDir = process.cwd()) {
   }
   return null;
 }
-async function resolvePat(org) {
+async function resolveAuthCredential(org) {
   const envPat = process.env.AZDO_PAT;
   if (envPat && envPat.length > 0) {
-    return { pat: envPat, source: "env" };
+    return { pat: envPat, source: "env", kind: "pat" };
   }
-  const storedPat = await getPat(org);
-  if (storedPat !== null) {
-    return { pat: storedPat, source: "credential-store" };
+  const stored = await getStoredCredential(org);
+  if (stored !== null) {
+    if (stored.kind === "pat") {
+      return { pat: stored.token, source: "credential-store", kind: "pat" };
+    }
+    const fresh = await refreshIfNeeded(org, stored);
+    return {
+      pat: fresh.accessToken,
+      source: "credential-store",
+      kind: "oauth",
+      accountId: fresh.accountId
+    };
   }
   const dotEnvPat = findDotEnvPat();
   if (dotEnvPat !== null) {
-    return { pat: dotEnvPat, source: "env" };
+    return { pat: dotEnvPat, source: "env", kind: "pat" };
   }
   return null;
 }
-async function requirePat(org) {
-  const cred = await resolvePat(org);
+async function requireAuthCredential(org) {
+  const cred = await resolveAuthCredential(org);
   if (cred !== null) {
     return cred;
   }
-  throw new Error(
-    `No PAT available for org "${org}". Set AZDO_PAT environment variable or run \`azdo auth --org ${org}\`.`
-  );
+  throw new CredentialMissingError(org);
 }
 async function validatePatAgainstAzdo(pat, org) {
   const url = `https://dev.azure.com/${encodeURIComponent(org)}/_apis/projects?$top=1&api-version=7.1`;
@@ -791,25 +640,168 @@ async function validatePatAgainstAzdo(pat, org) {
   }
   throw new Error(`Azure DevOps returned HTTP ${response.status} while validating PAT for org "${org}".`);
 }
+var LOGIN_FAILURE_REASONS = /* @__PURE__ */ new Set([
+  "user-cancelled",
+  "port-conflict",
+  "state-mismatch",
+  "redirect-mismatch",
+  "idp-error",
+  "timeout",
+  "expired_token",
+  "access_denied"
+]);
+function extractLoginFailureReason(err) {
+  if (typeof err === "object" && err !== null && "reason" in err) {
+    const r = err.reason;
+    if (typeof r === "string" && LOGIN_FAILURE_REASONS.has(r)) {
+      return r;
+    }
+  }
+  return "unknown";
+}
+async function loginWithOAuth(org, opts = {}) {
+  const oauthConfig = resolveOAuthConfig({
+    clientIdOverride: opts.clientIdOverride,
+    tenantIdOverride: opts.tenantIdOverride,
+    scopesOverride: opts.scopesOverride
+  });
+  const isHeadlessRuntime = () => {
+    if (opts.forceHeadless) return true;
+    if (process.platform === "linux") {
+      return !process.env.DISPLAY || process.env.DISPLAY.length === 0;
+    }
+    return false;
+  };
+  const useDeviceCode = opts.flow === "device-code" || opts.flow !== "auth-code" && isHeadlessRuntime();
+  appendAuthAuditEvent({
+    event: "oauth-login-started",
+    org,
+    backend: probeBackend(),
+    flow: useDeviceCode ? "device-code" : "auth-code",
+    clientIdSource: oauthConfig.clientIdSource
+  });
+  let credential;
+  let flowUsed;
+  try {
+    if (useDeviceCode) {
+      const r = await runDeviceCodeFlow(org, oauthConfig);
+      credential = r.credential;
+      flowUsed = "device-code";
+    } else {
+      const r = await runAuthCodeFlow(org, oauthConfig);
+      credential = r.credential;
+      flowUsed = "auth-code";
+    }
+  } catch (err) {
+    appendAuthAuditEvent({
+      event: "oauth-login-failed",
+      org,
+      backend: probeBackend(),
+      flow: useDeviceCode ? "device-code" : "auth-code",
+      reason: extractLoginFailureReason(err)
+    });
+    throw err;
+  }
+  await storeOAuthCredential(org, credential);
+  appendAuthAuditEvent({
+    event: "oauth-login-success",
+    org,
+    backend: probeBackend(),
+    flow: flowUsed,
+    clientIdSource: oauthConfig.clientIdSource,
+    accountId: credential.accountId,
+    scope: credential.scope,
+    tokenLifetimeSec: credential.expiresAt - credential.issuedAt
+  });
+  return {
+    org,
+    kind: "oauth",
+    accountId: credential.accountId,
+    expiresAt: credential.expiresAt,
+    scope: credential.scope,
+    flowUsed
+  };
+}
+async function logout(opts = {}) {
+  if (opts.all) {
+    const orgs = await listOrgsWithStoredPat();
+    const removed = [];
+    for (const o of orgs) {
+      const cred2 = await getStoredCredential(o);
+      const ok2 = await deletePat(o);
+      if (ok2 && cred2 !== null) {
+        removed.push({ org: o, kind: cred2.kind });
+      }
+    }
+    return { removed };
+  }
+  if (!opts.org) {
+    throw new Error("logout requires an org or --all");
+  }
+  const cred = await getStoredCredential(opts.org);
+  const ok = await deletePat(opts.org);
+  return { removed: ok && cred !== null ? [{ org: opts.org, kind: cred.kind }] : [] };
+}
+async function status() {
+  const orgs = await listOrgsWithStoredPat();
+  const out = [];
+  for (const org of orgs) {
+    const cred = await getStoredCredential(org);
+    if (cred === null) continue;
+    if (cred.kind === "pat") {
+      out.push({ org, kind: "pat", backend: probeBackend() });
+    } else {
+      out.push({
+        org,
+        kind: "oauth",
+        accountId: cred.accountId,
+        expiresAt: cred.expiresAt,
+        scope: cred.scope,
+        backend: probeBackend()
+      });
+    }
+  }
+  return { orgs: out };
+}
 
 // src/services/git-remote.ts
 import { execSync } from "child_process";
+
+// src/services/remote-warning.ts
+var WARNING = "azdo: warning: origin includes embedded credentials; consider removing them with 'git remote set-url origin <clean-url>'\n";
+var warned = false;
+function noticeCredentialBearingRemote() {
+  if (warned) {
+    return;
+  }
+  warned = true;
+  try {
+    process.stderr.write(WARNING);
+  } catch {
+  }
+}
+
+// src/services/git-remote.ts
 var patterns = [
-  // HTTPS (current): https://dev.azure.com/{org}/{project}/_git/{repo}
-  /^https?:\/\/dev\.azure\.com\/([^/]+)\/([^/]+)\/_git\/([^/]+)$/,
-  // HTTPS (legacy + DefaultCollection): https://{org}.visualstudio.com/DefaultCollection/{project}/_git/{repo}
-  /^https?:\/\/([^.]+)\.visualstudio\.com\/DefaultCollection\/([^/]+)\/_git\/([^/]+)$/,
-  // HTTPS (legacy): https://{org}.visualstudio.com/{project}/_git/{repo}
-  /^https?:\/\/([^.]+)\.visualstudio\.com\/([^/]+)\/_git\/([^/]+)$/,
-  // SSH (current): git@ssh.dev.azure.com:v3/{org}/{project}/{repo}
-  /^git@ssh\.dev\.azure\.com:v3\/([^/]+)\/([^/]+)\/([^/]+)$/,
-  // SSH (legacy): {org}@vs-ssh.visualstudio.com:v3/{org}/{project}/{repo}
-  /^[^@]+@vs-ssh\.visualstudio\.com:v3\/([^/]+)\/([^/]+)\/([^/]+)$/
+  // HTTPS (current): https://[user[:token]@]dev.azure.com/{org}/{project}/_git/{repo}[.git]
+  /^https?:\/\/(?:[^@/]+@)?dev\.azure\.com\/([^/]+)\/([^/]+)\/_git\/([^/]+?)(?:\.git)?$/,
+  // HTTPS (legacy + DefaultCollection): https://[user[:token]@]{org}.visualstudio.com/DefaultCollection/{project}/_git/{repo}[.git]
+  /^https?:\/\/(?:[^@/]+@)?([^.]+)\.visualstudio\.com\/DefaultCollection\/([^/]+)\/_git\/([^/]+?)(?:\.git)?$/,
+  // HTTPS (legacy): https://[user[:token]@]{org}.visualstudio.com/{project}/_git/{repo}[.git]
+  /^https?:\/\/(?:[^@/]+@)?([^.]+)\.visualstudio\.com\/([^/]+)\/_git\/([^/]+?)(?:\.git)?$/,
+  // SSH (current): git@ssh.dev.azure.com:v3/{org}/{project}/{repo}[.git]
+  /^git@ssh\.dev\.azure\.com:v3\/([^/]+)\/([^/]+)\/([^/]+?)(?:\.git)?$/,
+  // SSH (legacy): {org}@vs-ssh.visualstudio.com:v3/{org}/{project}/{repo}[.git]
+  /^[^@]+@vs-ssh\.visualstudio\.com:v3\/([^/]+)\/([^/]+)\/([^/]+?)(?:\.git)?$/
 ];
+var httpsUserinfo = /^https?:\/\/[^@/]+@/;
 function parseAzdoRemote(url) {
   for (const pattern of patterns) {
     const match = pattern.exec(url);
     if (match) {
+      if (httpsUserinfo.test(url)) {
+        noticeCredentialBearingRemote();
+      }
       const project = match[2];
       if (/^DefaultCollection$/i.test(project)) {
         return { org: match[1], project: "" };
@@ -836,6 +828,9 @@ function parseRepoName(url) {
   for (const pattern of patterns) {
     const match = pattern.exec(url);
     if (match) {
+      if (httpsUserinfo.test(url)) {
+        noticeCredentialBearingRemote();
+      }
       return match[3];
     }
   }
@@ -1073,12 +1068,12 @@ function stripHtml(html) {
   text = text.replaceAll(/<\/?(p|div)>/gi, "\n");
   text = text.replaceAll(/<li>/gi, "\n");
   text = removeHtmlTags(text);
-  text = text.replaceAll("&amp;", "&");
   text = text.replaceAll("&lt;", "<");
   text = text.replaceAll("&gt;", ">");
   text = text.replaceAll("&quot;", '"');
   text = text.replaceAll("&#39;", "'");
   text = text.replaceAll("&nbsp;", " ");
+  text = text.replaceAll("&amp;", "&");
   text = text.replaceAll(/\n{3,}/g, "\n\n");
   return text.trim();
 }
@@ -1188,9 +1183,9 @@ function createGetItemCommand() {
       let context;
       try {
         context = resolveContext(options);
-        const credential = await requirePat(context.org);
+        const credential = await requireAuthCredential(context.org);
         const fieldsList = options.fields === void 0 ? parseRequestedFields(loadConfig().fields) : parseRequestedFields(options.fields);
-        const workItem = await getWorkItem(context, id, credential.pat, fieldsList);
+        const workItem = await getWorkItem(context, id, credential, fieldsList);
         const markdownEnabled = options.markdown ?? loadConfig().markdown ?? false;
         const output = formatWorkItem(workItem, options.short ?? false, markdownEnabled);
         process.stdout.write(output + "\n");
@@ -1229,63 +1224,6 @@ function createClearPatCommand() {
 
 // 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) {
@@ -1293,9 +1231,9 @@ async function readStdinToString() {
   }
   return Buffer.concat(chunks).toString("utf8");
 }
-async function confirmOverwrite(org) {
+async function promptYesNo(prompt) {
   if (!process.stdin.isTTY) return true;
-  process.stderr.write(`A PAT is already stored for org ${org}. Overwrite? [y/N] `);
+  process.stderr.write(prompt);
   return await new Promise((resolve2) => {
     process.stdin.setEncoding("utf8");
     let answered = false;
@@ -1311,7 +1249,23 @@ async function confirmOverwrite(org) {
     process.stdin.on("data", handler);
   });
 }
-async function handleAuthRoot(options) {
+async function confirmOverwrite(org) {
+  return promptYesNo(`A PAT is already stored for org ${org}. Overwrite? [y/N] `);
+}
+async function confirmOverwriteCredential(org, existingKind) {
+  const label = existingKind === "oauth" ? "OAuth credential" : "PAT";
+  return promptYesNo(`A ${label} is already stored for org ${org}. The new login will replace it. Continue? [y/N] `);
+}
+function rejectMutuallyExclusive(opts) {
+  if (opts.usePat && opts.deviceCode) {
+    return "--use-pat and --device-code are mutually exclusive (PAT has no device-code flow).";
+  }
+  if (opts.usePat && (opts.clientId || opts.tenantId || opts.scopes)) {
+    return "--use-pat cannot be combined with OAuth-only flags (--client-id / --tenant-id / --scopes).";
+  }
+  return null;
+}
+async function handlePatLogin(options) {
   const resolved = resolveOrg({ org: options.org });
   if (!resolved) {
     process.stderr.write(`${formatResolutionError()}
@@ -1377,7 +1331,145 @@ async function handleAuthRoot(options) {
   process.stdout.write(`PAT stored for org ${org} in ${probeBackend()}.
 `);
 }
+async function ensureOverwriteConfirmed(org) {
+  try {
+    const existing = await getStoredCredential(org);
+    if (existing === null || !process.stdin.isTTY) return "ok";
+    const ok = await confirmOverwriteCredential(org, existing.kind);
+    return ok ? "ok" : "aborted";
+  } catch (err) {
+    if (err instanceof CredentialStoreUnavailableError) {
+      process.stderr.write(`${err.message}
+`);
+      return "unavailable";
+    }
+    throw err;
+  }
+}
+function buildOAuthLoginOptions(options) {
+  return {
+    flow: options.deviceCode ? "device-code" : "auto",
+    clientIdOverride: options.clientId,
+    tenantIdOverride: options.tenantId,
+    scopesOverride: options.scopes ? options.scopes.split(/\s+/).filter(Boolean) : void 0
+  };
+}
+function reportOAuthFailure(err) {
+  const reason = typeof err === "object" && err !== null && "reason" in err ? err.reason : null;
+  const msg = err.message;
+  process.stderr.write(reason ? `OAuth login failed (${reason}): ${msg}
+` : `OAuth login failed: ${msg}
+`);
+  const noDisplay = process.platform === "linux" && (!process.env.DISPLAY || process.env.DISPLAY.length === 0);
+  if (noDisplay) {
+    process.stderr.write("Tip: this host has no DISPLAY; pass --device-code to use the headless flow.\n");
+  } else if (reason === "port-conflict") {
+    process.stderr.write("Tip: another process is using the loopback callback port. Try again or pass --device-code.\n");
+  }
+}
+async function handleOAuthLogin(options) {
+  const resolved = resolveOrg({ org: options.org });
+  if (!resolved) {
+    process.stderr.write(`${formatResolutionError()}
+`);
+    process.exitCode = 3;
+    return;
+  }
+  const org = resolved.org;
+  const confirm = await ensureOverwriteConfirmed(org);
+  if (confirm === "aborted") {
+    process.stderr.write("Aborted. Existing credential preserved.\n");
+    process.exitCode = 1;
+    return;
+  }
+  if (confirm === "unavailable") {
+    process.exitCode = 4;
+    return;
+  }
+  try {
+    const result = await loginWithOAuth(org, buildOAuthLoginOptions(options));
+    process.stdout.write(
+      `Logged in to ${org} via OAuth (${result.flowUsed}). Account: ${result.accountId}; expires ${new Date(result.expiresAt * 1e3).toISOString()}.
+`
+    );
+  } catch (err) {
+    reportOAuthFailure(err);
+    process.exitCode = 1;
+  }
+}
+async function handleAuthRoot(options) {
+  const conflict = rejectMutuallyExclusive(options);
+  if (conflict) {
+    process.stderr.write(`${conflict}
+`);
+    process.exitCode = 2;
+    return;
+  }
+  await handlePatLogin(options);
+}
+async function handleLoginSubcommand(options) {
+  const conflict = rejectMutuallyExclusive(options);
+  if (conflict) {
+    process.stderr.write(`${conflict}
+`);
+    process.exitCode = 2;
+    return;
+  }
+  if (options.fromStdin || options.usePat) {
+    await handlePatLogin(options);
+    return;
+  }
+  await handleOAuthLogin(options);
+}
+async function handleStatusJson() {
+  try {
+    const report = await status();
+    process.stdout.write(`${JSON.stringify(report)}
+`);
+  } catch (err) {
+    if (err instanceof CredentialStoreUnavailableError) {
+      process.stderr.write(`${err.message}
+`);
+      process.exitCode = 4;
+      return;
+    }
+    throw err;
+  }
+}
 async function handleStatus(options, org) {
+  if (options.json) {
+    let backend2;
+    let value2;
+    try {
+      backend2 = probeBackend();
+      value2 = await getPat(org);
+    } catch (err) {
+      if (err instanceof CredentialStoreUnavailableError) {
+        process.stderr.write(`${err.message}
+`);
+        process.exitCode = 4;
+        return;
+      }
+      throw err;
+    }
+    const storedEvents2 = readAuditEvents().filter((ev) => ev.org === org && ev.event === "auth.store");
+    const last2 = storedEvents2.at(-1);
+    const updatedAt2 = last2?.ts ?? null;
+    if (!value2) {
+      process.stdout.write(
+        `${JSON.stringify({ org, backend: backend2, stored: false, masked: null, updated_at: updatedAt2 })}
+`
+      );
+      process.exitCode = 1;
+      return;
+    }
+    const masked2 = maskedDisplay(value2);
+    process.stdout.write(
+      `${JSON.stringify({ org, backend: backend2, stored: true, masked: masked2, updated_at: updatedAt2 })}
+`
+    );
+    return;
+  }
   let backend;
   let value;
   try {
@@ -1393,39 +1485,25 @@ async function handleStatus(options, org) {
     throw err;
   }
   const storedEvents = readAuditEvents().filter((ev) => ev.org === org && ev.event === "auth.store");
-  const last = storedEvents[storedEvents.length - 1];
+  const last = storedEvents.at(-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}
+    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}
+  process.stdout.write(
+    `Organization: ${org}
 Backend:      ${backend}
 Stored:       yes
 Identifier:   ${masked}
 ` + (updatedAt ? `Last updated: ${updatedAt}
 ` : "")
-    );
-  }
+  );
 }
 async function handleLogout(options, orgFromGlobal) {
   if (options.all && orgFromGlobal) {
@@ -1434,9 +1512,16 @@ async function handleLogout(options, orgFromGlobal) {
     return;
   }
   if (options.all) {
-    let orgs;
     try {
-      orgs = await listOrgsWithStoredPat();
+      const result = await logout({ all: true });
+      if (result.removed.length === 0) {
+        process.stdout.write("No stored credentials to remove.\n");
+        return;
+      }
+      for (const r of result.removed) {
+        process.stdout.write(`Removed ${r.kind} credential for org ${r.org}.
+`);
+      }
     } catch (err) {
       if (err instanceof CredentialStoreUnavailableError) {
         process.stderr.write(`${err.message}
@@ -1444,22 +1529,9 @@ async function handleLogout(options, orgFromGlobal) {
         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.stderr.write(`Failed to remove credentials: ${err.message}
 `);
-        process.exitCode = 1;
-      }
+      process.exitCode = 1;
     }
     return;
   }
@@ -1473,10 +1545,10 @@ async function handleLogout(options, orgFromGlobal) {
   try {
     const removed = await deletePat(resolved.org);
     if (removed) {
-      process.stdout.write(`PAT removed for org ${resolved.org}.
+      process.stdout.write(`Credential removed for org ${resolved.org}.
 `);
     } else {
-      process.stdout.write(`No stored PAT found for org ${resolved.org}.
+      process.stdout.write(`No stored credential for org ${resolved.org}.
 `);
     }
   } catch (err) {
@@ -1491,14 +1563,70 @@ async function handleLogout(options, orgFromGlobal) {
 }
 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) => {
+  command.description(
+    "Manage Azure DevOps authentication. Use `azdo auth login` for OAuth (default); the bare `azdo auth` form preserves the legacy PAT-prompt path for back-compat."
+  );
+  command.option("--org <name>", "Azure DevOps organization (flag wins over auto-detect / config)").option("--from-stdin", "read PAT from stdin instead of prompting (implies --use-pat)", false).option("--no-browser", "do not open the Azure DevOps PAT page in a browser (PAT path only)").option("--use-pat", "use Personal Access Token instead of OAuth (legacy path)", false).option("--device-code", "use OAuth device-code flow (headless hosts; OAuth only)", false).option("--client-id <id>", "override the default OAuth client id (FR-013 override path)").option("--tenant-id <id>", "override the default OAuth tenant id (default: common)").option("--scopes <scopes>", "space-separated OAuth scope override (advanced; default mirrors PAT scope table)");
+  command.addHelpText(
+    "after",
+    `
+Default flow (OAuth, browser-based):
+  azdo auth login --org <name>
+  \u2192 opens the default browser for OAuth (Microsoft Entra v2 + PKCE).
+
+Headless / no-browser:
+  azdo auth login --org <name> --device-code
+
+PAT path (legacy, opt-in):
+  azdo auth login --org <name> --use-pat
+  azdo auth --org <name>            # back-compat alias of the above
+
+OAuth scope set \u2014 shipped first-party client (default install):
+  ${firstPartyShippedScopes().join("\n  ")}
+  (uses ${AZDO_RESOURCE_ID}/.default \u2014 per-scope consent is unavailable
+  against a client we do not own; .default grants the VS client's
+  pre-authorized AzDO permissions in one step.)
+
+OAuth scope set \u2014 self-registered apps (--client-id / AZDO_OAUTH_CLIENT_ID):
+  ${defaultScopes().join("\n  ")}
+  (FR-016, mirrors the PAT scope table \u2014 see docs/oauth-app-registration.md)
+
+For self-registered OAuth apps (locked-down tenants), see docs/oauth-app-registration.md
+\u2014 that same guide is the maintainer reference for the project's shared client id.
+
+Note: stored credentials may coexist as 'pat' or 'oauth' across orgs (FR-007).
+Note: \`azdo auth\` (no subcommand) preserves the legacy PAT-prompt entry point;
+      \`azdo auth login\` is the spec-canonical name and defaults to OAuth.`
+  ).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);
+  const loginCmd = command.command("login").description("Authenticate against Azure DevOps (OAuth default; --use-pat for PAT)").option("--org <name>", "Azure DevOps organization (defaults: git remote \u2192 config)");
+  loginCmd.action(async () => {
+    const merged = loginCmd.optsWithGlobals();
+    await handleLoginSubcommand(merged);
+  });
+  const statusCmd = command.command("status").description("Report stored credentials (kind, org, account/expiry, backend) \u2014 never the token").option("--json", "emit JSON", false);
   statusCmd.action(async (options) => {
     const globals = statusCmd.optsWithGlobals();
+    if (!globals.org) {
+      if (options.json) {
+        await handleStatusJson();
+        return;
+      }
+      const report = await status();
+      if (report.orgs.length === 0) {
+        process.stdout.write("No stored credentials.\n");
+        return;
+      }
+      for (const e of report.orgs) {
+        const expiry = e.expiresAt ? new Date(e.expiresAt * 1e3).toISOString() : "n/a";
+        process.stdout.write(
+          `${e.org}	${e.kind}	${e.accountId ?? ""}	${expiry}
+`
+        );
+      }
+      return;
+    }
     const resolved = resolveOrg({ org: globals.org });
     if (!resolved) {
       process.stderr.write(`${formatResolutionError()}
@@ -1508,7 +1636,11 @@ function createAuthCommand() {
     }
     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);
+  statusCmd.addHelpText(
+    "after",
+    "\nStored credentials may be of kind `pat` or `oauth` and may coexist across orgs (FR-007).\n"
+  );
+  const logoutCmd = command.command("logout").description("Remove the stored credential for an org (or all orgs with --all)").option("--all", "remove every stored credential (PAT and OAuth)", false);
   logoutCmd.action(async (options) => {
     const globals = logoutCmd.optsWithGlobals();
     await handleLogout(options, globals.org);
@@ -1690,11 +1822,11 @@ function createSetStateCommand() {
       let context;
       try {
         context = resolveContext(options);
-        const credential = await requirePat(context.org);
+        const credential = await requireAuthCredential(context.org);
         const operations = [
           { op: "add", path: "/fields/System.State", value: state }
         ];
-        const result = await updateWorkItem(context, id, credential.pat, "System.State", operations);
+        const result = await updateWorkItem(context, id, credential, "System.State", operations);
         if (options.json) {
           process.stdout.write(
             JSON.stringify({
@@ -1740,12 +1872,12 @@ function createAssignCommand() {
       let context;
       try {
         context = resolveContext(options);
-        const credential = await requirePat(context.org);
+        const credential = await requireAuthCredential(context.org);
         const value = options.unassign ? "" : name;
         const operations = [
           { op: "add", path: "/fields/System.AssignedTo", value }
         ];
-        const result = await updateWorkItem(context, id, credential.pat, "System.AssignedTo", operations);
+        const result = await updateWorkItem(context, id, credential, "System.AssignedTo", operations);
         if (options.json) {
           process.stdout.write(
             JSON.stringify({
@@ -1780,11 +1912,11 @@ function createSetFieldCommand() {
       let context;
       try {
         context = resolveContext(options);
-        const credential = await requirePat(context.org);
+        const credential = await requireAuthCredential(context.org);
         const operations = [
           { op: "add", path: `/fields/${field}`, value }
         ];
-        const result = await updateWorkItem(context, id, credential.pat, field, operations);
+        const result = await updateWorkItem(context, id, credential, field, operations);
         if (options.json) {
           process.stdout.write(
             JSON.stringify({
@@ -1818,8 +1950,8 @@ function createGetMdFieldCommand() {
       let context;
       try {
         context = resolveContext(options);
-        const credential = await requirePat(context.org);
-        const value = await getWorkItemFieldValue(context, id, credential.pat, field);
+        const credential = await requireAuthCredential(context.org);
+        const value = await getWorkItemFieldValue(context, id, credential, field);
         if (value === null) {
           process.stdout.write("\n");
         } else {
@@ -1906,12 +2038,12 @@ function createSetMdFieldCommand() {
       let context;
       try {
         context = resolveContext(options);
-        const credential = await requirePat(context.org);
+        const credential = await requireAuthCredential(context.org);
         const operations = [
           { op: "add", path: `/fields/${field}`, value: content },
           { op: "add", path: `/multilineFieldsFormat/${field}`, value: "Markdown" }
         ];
-        const result = await updateWorkItem(context, id, credential.pat, field, operations);
+        const result = await updateWorkItem(context, id, credential, field, operations);
         formatOutput(result, options, field);
       } catch (err) {
         handleCommandError(err, id, context, "write");
@@ -2222,15 +2354,15 @@ function createUpsertCommand() {
         ensureTitleForCreate(document.fields);
       }
       const operations = toPatchOperations(document.fields, action);
-      const credential = await requirePat(context.org);
+      const credential = await requireAuthCredential(context.org);
       let writeResult;
       if (action === "created") {
-        writeResult = await createWorkItem(context, createType, credential.pat, operations);
+        writeResult = await createWorkItem(context, createType, credential, operations);
       } else {
         if (id === void 0) {
           fail2("Work item ID is required for updates.");
         }
-        writeResult = await applyWorkItemPatch(context, id, credential.pat, operations);
+        writeResult = await applyWorkItemPatch(context, id, credential, operations);
       }
       const result = buildUpsertResult(
         action,
@@ -2288,8 +2420,8 @@ function createListFieldsCommand() {
       let context;
       try {
         context = resolveContext(options);
-        const credential = await requirePat(context.org);
-        const fields = await getWorkItemFields(context, id, credential.pat);
+        const credential = await requireAuthCredential(context.org);
+        const fields = await getWorkItemFields(context, id, credential);
         if (options.json) {
           process.stdout.write(JSON.stringify({ id, fields }, null, 2) + "\n");
         } else {
@@ -2343,9 +2475,9 @@ function mapPullRequest(repo, pullRequest) {
     url: pullRequest._links?.web?.href ?? null
   };
 }
-function mapPullRequestCheckName(status) {
-  const genre = status.context?.genre?.trim();
-  const name = status.context?.name?.trim();
+function mapPullRequestCheckName(status2) {
+  const genre = status2.context?.genre?.trim();
+  const name = status2.context?.name?.trim();
   if (genre && name) {
     return `${genre}/${name}`;
   }
@@ -2355,21 +2487,21 @@ function mapPullRequestCheckName(status) {
   if (genre) {
     return genre;
   }
-  return `Status #${status.id}`;
+  return `Status #${status2.id}`;
 }
-function mapPullRequestCheck(status) {
-  if (status.state === "notApplicable" || status.state === "notSet") {
+function mapPullRequestCheck(status2) {
+  if (status2.state === "notApplicable" || status2.state === "notSet") {
     return null;
   }
   return {
-    id: status.id,
-    state: status.state,
-    name: mapPullRequestCheckName(status),
-    description: status.description ?? null,
-    targetUrl: status.targetUrl ?? null,
-    createdBy: status.createdBy?.displayName ?? null,
-    createdAt: status.creationDate ?? null,
-    updatedAt: status.updatedDate ?? null
+    id: status2.id,
+    state: status2.state,
+    name: mapPullRequestCheckName(status2),
+    description: status2.description ?? null,
+    targetUrl: status2.targetUrl ?? null,
+    createdBy: status2.createdBy?.displayName ?? null,
+    createdAt: status2.creationDate ?? null,
+    updatedAt: status2.updatedDate ?? null
   };
 }
 function mapComment(comment) {
@@ -2405,8 +2537,8 @@ function toActiveCommentThread(thread) {
   };
 }
 var RESOLVED_THREAD_STATUSES = /* @__PURE__ */ new Set(["fixed", "wontFix", "closed", "byDesign"]);
-function isThreadResolved(status) {
-  return RESOLVED_THREAD_STATUSES.has(status);
+function isThreadResolved(status2) {
+  return RESOLVED_THREAD_STATUSES.has(status2);
 }
 async function readJsonResponse(response) {
   if (!response.ok) {
@@ -2414,7 +2546,7 @@ async function readJsonResponse(response) {
   }
   return response.json();
 }
-async function patchThreadStatus(context, repo, pat, prId, threadId, status) {
+async function patchThreadStatus(context, repo, cred, prId, threadId, status2) {
   const url = new URL(
     `https://dev.azure.com/${encodeURIComponent(context.org)}/${encodeURIComponent(context.project)}/_apis/git/repositories/${encodeURIComponent(repo)}/pullRequests/${prId}/threads/${threadId}`
   );
@@ -2422,41 +2554,41 @@ async function patchThreadStatus(context, repo, pat, prId, threadId, status) {
   const response = await fetchWithErrors(url.toString(), {
     method: "PATCH",
     headers: {
-      ...authHeaders(pat),
+      ...authHeaders(cred),
       "Content-Type": "application/json"
     },
-    body: JSON.stringify({ status })
+    body: JSON.stringify({ status: status2 })
   });
   const data = await readJsonResponse(response);
   return toActiveCommentThread(data);
 }
-async function getPullRequestById(context, repo, pat, prId) {
+async function getPullRequestById(context, repo, cred, prId) {
   const url = new URL(
     `https://dev.azure.com/${encodeURIComponent(context.org)}/${encodeURIComponent(context.project)}/_apis/git/repositories/${encodeURIComponent(repo)}/pullRequests/${prId}`
   );
   url.searchParams.set("api-version", "7.1");
-  const response = await fetchWithErrors(url.toString(), { headers: authHeaders(pat) });
+  const response = await fetchWithErrors(url.toString(), { headers: authHeaders(cred) });
   const data = await readJsonResponse(response);
   return mapPullRequest(repo, data);
 }
-async function listPullRequests(context, repo, pat, sourceBranch, opts) {
+async function listPullRequests(context, repo, cred, sourceBranch, opts) {
   const response = await fetchWithErrors(
     buildPullRequestsUrl(context, repo, sourceBranch, opts).toString(),
-    { headers: authHeaders(pat) }
+    { headers: authHeaders(cred) }
   );
   const data = await readJsonResponse(response);
   return data.value.map((pullRequest) => mapPullRequest(repo, pullRequest));
 }
-async function getPullRequestChecks(context, repo, pat, prId) {
+async function getPullRequestChecks(context, repo, cred, prId) {
   const response = await fetchWithErrors(
     buildPullRequestStatusesUrl(context, repo, prId).toString(),
-    { headers: authHeaders(pat) }
+    { headers: authHeaders(cred) }
   );
   const data = await readJsonResponse(response);
   return data.value.map(mapPullRequestCheck).filter((check) => check !== null);
 }
-async function openPullRequest(context, repo, pat, sourceBranch, title, description) {
-  const existing = await listPullRequests(context, repo, pat, sourceBranch, {
+async function openPullRequest(context, repo, cred, sourceBranch, title, description) {
+  const existing = await listPullRequests(context, repo, cred, sourceBranch, {
     status: "active",
     targetBranch: "develop"
   });
@@ -2484,7 +2616,7 @@ async function openPullRequest(context, repo, pat, sourceBranch, title, descript
   const response = await fetchWithErrors(url.toString(), {
     method: "POST",
     headers: {
-      ...authHeaders(pat),
+      ...authHeaders(cred),
       "Content-Type": "application/json"
     },
     body: JSON.stringify(payload)
@@ -2497,12 +2629,12 @@ async function openPullRequest(context, repo, pat, sourceBranch, title, descript
     pullRequest: mapPullRequest(repo, data)
   };
 }
-async function getPullRequestThreads(context, repo, pat, prId) {
+async function getPullRequestThreads(context, repo, cred, prId) {
   const url = new URL(
     `https://dev.azure.com/${encodeURIComponent(context.org)}/${encodeURIComponent(context.project)}/_apis/git/repositories/${encodeURIComponent(repo)}/pullRequests/${prId}/threads`
   );
   url.searchParams.set("api-version", "7.1");
-  const response = await fetchWithErrors(url.toString(), { headers: authHeaders(pat) });
+  const response = await fetchWithErrors(url.toString(), { headers: authHeaders(cred) });
   const data = await readJsonResponse(response);
   return data.value.map(mapThread).filter((thread) => thread !== null);
 }
@@ -2515,6 +2647,21 @@ function parsePositivePrNumber(raw) {
   const n = Number.parseInt(raw, 10);
   return Number.isFinite(n) && n > 0 ? n : null;
 }
+var PR_NUMBER_HELP = "target the pull request with this numeric id, instead of the current branch's PR. When omitted, the CLI auto-detects the pull request whose source branch equals refs/heads/<current branch> in the Azure DevOps repository identified by the origin remote; if zero or more than one open PR matches, the command fails with a message naming the searched branch.";
+function configureUnwrappedHelp(command) {
+  return command.configureHelp({ helpWidth: 1e3 });
+}
+function autoDetectZeroMatch(branch) {
+  return `No open pull request matches branch ${branch}. Pass --pr-number to target a specific PR, or push the branch and open a pull request.`;
+}
+function autoDetectMultiMatch(branch, ids) {
+  return `Multiple open pull requests match branch ${branch}: ${ids.map((id) => `#${id}`).join(", ")}. Re-run with --pr-number to choose.`;
+}
+function writeContractError(line) {
+  process.stderr.write(`${line}
+`);
+  process.exitCode = 1;
+}
 function formatBranchName(refName) {
   return refName.startsWith("refs/heads/") ? refName.slice("refs/heads/".length) : refName;
 }
@@ -2569,8 +2716,8 @@ function formatPullRequestBlock(pullRequest) {
     ...formatPullRequestChecks(pullRequest.checks)
   ].join("\n");
 }
-function threadStatusLabel(status) {
-  return isThreadResolved(status) ? "resolved" : status;
+function threadStatusLabel(status2) {
+  return isThreadResolved(status2) ? "resolved" : status2;
 }
 function formatThreads(prId, title, threads) {
   const lines = [`Comment threads for pull request #${prId}: ${title}`];
@@ -2587,12 +2734,12 @@ async function resolvePrCommandContext(options, resolveOpts = {}) {
   const context = resolveContext(options);
   const repo = detectRepoName();
   const branch = requireBranch ? getCurrentBranch() : null;
-  const credential = await requirePat(context.org);
+  const credential = await requireAuthCredential(context.org);
   return {
     context,
     repo,
     branch,
-    pat: credential.pat
+    pat: credential
   };
 }
 function createPrStatusCommand() {
@@ -2690,7 +2837,7 @@ ${result.pullRequest.url ?? "\u2014"}
 }
 function createPrCommentsCommand() {
   const command = new Command12("comments");
-  command.description("List pull request comment threads for the current branch").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--pr-number <N>", "target the pull request with this numeric id, instead of the current branch's PR").option("--hide-resolved", "hide threads whose status is resolved / won't fix / closed / by design").option("--json", "output JSON").action(async (options) => {
+  configureUnwrappedHelp(command).description("List pull request comment threads for the current branch").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--pr-number <N>", PR_NUMBER_HELP).option("--hide-resolved", "hide threads whose status is resolved / won't fix / closed / by design").option("--json", "output JSON").action(async (options) => {
     validateOrgProjectPair(options);
     let context;
     let explicitPrId = null;
@@ -2722,12 +2869,11 @@ function createPrCommentsCommand() {
           status: "active"
         });
         if (pullRequests.length === 0) {
-          writeError(`No active pull request found for branch ${resolved.branch}.`);
+          writeContractError(autoDetectZeroMatch(resolved.branch));
           return;
         }
         if (pullRequests.length > 1) {
-          const ids = pullRequests.map((pr) => `#${pr.id}`).join(", ");
-          writeError(`Multiple active pull requests found for branch ${resolved.branch}: ${ids}. Use pr status to review them.`);
+          writeContractError(autoDetectMultiMatch(resolved.branch, pullRequests.map((pr) => pr.id)));
           return;
         }
         pullRequest = pullRequests[0];
@@ -2791,12 +2937,11 @@ async function resolveThreadTarget(threadIdRaw, options) {
       status: "active"
     });
     if (pullRequests.length === 0) {
-      writeError(`No active pull request found for branch ${resolved.branch}.`);
+      writeContractError(autoDetectZeroMatch(resolved.branch));
       return null;
     }
     if (pullRequests.length > 1) {
-      const ids = pullRequests.map((pr) => `#${pr.id}`).join(", ");
-      writeError(`Multiple active pull requests found for branch ${resolved.branch}: ${ids}. Use pr status to review them.`);
+      writeContractError(autoDetectMultiMatch(resolved.branch, pullRequests.map((pr) => pr.id)));
       return null;
     }
     pullRequest = pullRequests[0];
@@ -2864,14 +3009,14 @@ async function runThreadStateChange(threadIdRaw, options, direction) {
 }
 function createPrCommentResolveCommand() {
   const command = new Command12("comment-resolve");
-  command.description("Mark a pull request comment thread as resolved").argument("<threadId>", "numeric id of the thread to resolve").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--pr-number <N>", "target the pull request with this numeric id, instead of the current branch's PR").option("--json", "output JSON").action(async (threadIdRaw, options) => {
+  configureUnwrappedHelp(command).description("Mark a pull request comment thread as resolved").argument("<threadId>", "numeric id of the thread to resolve").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--pr-number <N>", PR_NUMBER_HELP).option("--json", "output JSON").action(async (threadIdRaw, options) => {
     await runThreadStateChange(threadIdRaw, options, "resolve");
   });
   return command;
 }
 function createPrCommentReopenCommand() {
   const command = new Command12("comment-reopen");
-  command.description("Reopen (set to active) a previously resolved pull request comment thread").argument("<threadId>", "numeric id of the thread to reopen").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--pr-number <N>", "target the pull request with this numeric id, instead of the current branch's PR").option("--json", "output JSON").action(async (threadIdRaw, options) => {
+  configureUnwrappedHelp(command).description("Reopen (set to active) a previously resolved pull request comment thread").argument("<threadId>", "numeric id of the thread to reopen").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project").option("--pr-number <N>", PR_NUMBER_HELP).option("--json", "output JSON").action(async (threadIdRaw, options) => {
     await runThreadStateChange(threadIdRaw, options, "reopen");
   });
   return command;
@@ -2915,8 +3060,8 @@ function createCommentsListCommand() {
     let context;
     try {
       context = resolveContext(options);
-      const credential = await requirePat(context.org);
-      const result = await listWorkItemComments(context, id, credential.pat);
+      const credential = await requireAuthCredential(context.org);
+      const result = await listWorkItemComments(context, id, credential);
       if (options.json) {
         process.stdout.write(`${JSON.stringify(result, null, 2)}
 `);
@@ -2946,9 +3091,9 @@ function createCommentsAddCommand() {
     let context;
     try {
       context = resolveContext(options);
-      const credential = await requirePat(context.org);
+      const credential = await requireAuthCredential(context.org);
       const format = options.markdown === true ? "markdown" : "html";
-      const result = await addWorkItemComment(context, id, credential.pat, text, format);
+      const result = await addWorkItemComment(context, id, credential, text, format);
       if (options.json) {
         process.stdout.write(`${JSON.stringify(result, null, 2)}
 `);
@@ -2984,14 +3129,14 @@ function createDownloadAttachmentCommand() {
       let context;
       try {
         context = resolveContext(options);
-        const credential = await requirePat(context.org);
+        const credential = await requireAuthCredential(context.org);
         const outputDir = options.output ?? ".";
         if (!existsSync4(outputDir)) {
           process.stderr.write(`Error: Output directory "${outputDir}" does not exist.
 `);
           process.exit(1);
         }
-        const workItem = await getWorkItem(context, id, credential.pat);
+        const workItem = await getWorkItem(context, id, credential);
         const attachment = workItem.attachments?.find(
           (a) => a.name === filename
         );
@@ -3002,7 +3147,7 @@ function createDownloadAttachmentCommand() {
           );
           process.exit(1);
         }
-        const data = await downloadAttachment(attachment.url, credential.pat);
+        const data = await downloadAttachment(attachment.url, credential);
         const outputPath = join2(outputDir, filename);
         await writeFile(outputPath, Buffer.from(data));
         process.stdout.write(