@iwas/mcp 0.0.0-stage → 1.0.0

package/dist/bin.js

@@ -0,0 +1,1833 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __commonJS = (cb, mod) => function __require() {
+  try {
+    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  } catch (e) {
+    throw mod = 0, e;
+  }
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// ../auth/dist/rbac/permissions.js
+var require_permissions = __commonJS({
+  "../auth/dist/rbac/permissions.js"(exports2) {
+    "use strict";
+    Object.defineProperty(exports2, "__esModule", { value: true });
+    exports2.MCP_OAUTH_SCOPES = exports2.OFFLINE_ACCESS_SCOPE = exports2.MCP_ELIGIBLE_PERMISSION_SET = exports2.MCP_ELIGIBLE_PERMISSIONS = exports2.SENSITIVE_MCP_RESOURCES = exports2.PERMISSION_SET = exports2.ALL_PERMISSIONS = exports2.CATALOG_DEFINITIONS = void 0;
+    exports2.isPermissionString = isPermissionString;
+    exports2.parsePermissionString = parsePermissionString;
+    exports2.isSensitiveMcpResource = isSensitiveMcpResource;
+    exports2.isMcpEligiblePermission = isMcpEligiblePermission;
+    exports2.partitionMcpScopes = partitionMcpScopes;
+    exports2.CATALOG_DEFINITIONS = {
+      organization: {
+        tier: "T",
+        actions: ["update", "delete"],
+        description: "Organization tenant profile and settings",
+        models: ["Organization", "OrganizationSetting", "OrganizationSubscription"],
+        mcpEligible: true
+      },
+      member: {
+        tier: "T",
+        actions: ["create", "update", "delete"],
+        description: "Organization member management",
+        models: ["Member"],
+        mcpEligible: true
+      },
+      invitation: {
+        tier: "T",
+        actions: ["create", "cancel"],
+        description: "Organization membership invitations",
+        models: ["Invitation"],
+        mcpEligible: true
+      },
+      location: {
+        tier: "T",
+        actions: ["read", "write", "delete"],
+        description: "Physical hotspot location management",
+        models: ["Location"],
+        mcpEligible: true
+      },
+      router: {
+        tier: "T",
+        actions: ["read", "write", "delete", "control"],
+        description: "Gateway router inventory, provisioning and control",
+        models: ["Router", "ZtpToken", "CoaQueue", "IpamAllocationCursor"],
+        mcpEligible: true
+      },
+      package: {
+        tier: "S",
+        actions: ["read", "write", "delete", "publish"],
+        description: "WiFi access package catalog (tenant + shared)",
+        models: ["Package", "VoucherPackage"],
+        mcpEligible: true
+      },
+      voucher: {
+        tier: "S",
+        actions: ["read", "write", "publish", "issue", "revoke"],
+        description: "Prepaid voucher codes and issuance (tenant + shared)",
+        models: ["Voucher", "VoucherIssuance", "VoucherUser"],
+        mcpEligible: true
+      },
+      session: {
+        tier: "T",
+        actions: ["read", "control"],
+        description: "Active and historical WiFi guest sessions",
+        models: ["WifiSession", "RadiusAccounting", "DeviceToken"],
+        mcpEligible: true
+      },
+      wallet: {
+        tier: "T",
+        actions: ["read", "topup", "charge", "refund", "freeze"],
+        description: "Prepaid wallet balances, topups and ledger transactions (SENSITIVE - MCP EXCLUDED)",
+        models: ["Wallet", "WalletTransaction", "TopupRequest"],
+        hasOwnQualifier: true,
+        mcpEligible: false
+      },
+      payment: {
+        tier: "T",
+        actions: ["read", "approve", "refund"],
+        description: "Inbound payment transactions and gateway integrations (SENSITIVE - MCP EXCLUDED)",
+        models: ["PaymentTransaction", "PaymentGatewayIntegration"],
+        hasOwnQualifier: true,
+        mcpEligible: false
+      },
+      subscription: {
+        tier: "T",
+        actions: ["read", "manage"],
+        description: "SaaS organization plan subscription and entitlements",
+        models: ["OrganizationSubscription"],
+        mcpEligible: true
+      },
+      partner: {
+        tier: "T",
+        actions: ["read", "manage", "payout:approve"],
+        description: "Affiliate/partner programs and payout requests",
+        models: ["Partner", "PartnerPayoutRequest"],
+        mcpEligible: true
+      },
+      campaign: {
+        tier: "T",
+        actions: ["read", "write"],
+        description: "Captive portal ad campaigns and lead capture",
+        models: ["AdCampaign", "LeadCapture"],
+        mcpEligible: true
+      },
+      notification: {
+        tier: "T",
+        actions: ["read", "send", "template:write"],
+        description: "Multi-channel notifications, templates and logs",
+        models: ["NotificationItem", "NotificationTemplate", "DeliveryLog"],
+        hasOwnQualifier: true,
+        mcpEligible: true
+      },
+      store: {
+        tier: "P",
+        actions: ["read", "write"],
+        description: "Public hardware/affiliate store catalog",
+        models: ["StoreProduct", "AffiliateClick"],
+        mcpEligible: true
+      },
+      blog: {
+        tier: "P",
+        actions: ["read", "write", "publish"],
+        description: "Company-wide editorial articles and CDN media",
+        models: ["BlogPost", "Media"],
+        hasOwnQualifier: true,
+        mcpEligible: true
+      },
+      analytics: {
+        tier: "D",
+        actions: ["read"],
+        description: "Aggregated usage, session and revenue metrics",
+        models: ["WifiSession", "Package", "PaymentTransaction"],
+        mcpEligible: true
+      },
+      diagnostics: {
+        tier: "P",
+        actions: ["read", "write"],
+        description: "System error events, MCP tool execution spans, flow events, issue triage and audit logs",
+        models: ["ErrorEvent", "McpToolSpan", "AuditLog", "SystemSetting", "FlowEvent", "IssueState"],
+        mcpEligible: true
+      }
+    };
+    exports2.ALL_PERMISSIONS = [
+      "organization:update",
+      "organization:delete",
+      "member:create",
+      "member:update",
+      "member:delete",
+      "invitation:create",
+      "invitation:cancel",
+      "location:read",
+      "location:write",
+      "location:delete",
+      "router:read",
+      "router:write",
+      "router:delete",
+      "router:control",
+      "package:read",
+      "package:write",
+      "package:delete",
+      "package:publish",
+      "voucher:read",
+      "voucher:write",
+      "voucher:publish",
+      "voucher:issue",
+      "voucher:revoke",
+      "session:read",
+      "session:control",
+      "wallet:read",
+      "wallet:topup",
+      "wallet:charge",
+      "wallet:refund",
+      "wallet:freeze",
+      "payment:read",
+      "payment:approve",
+      "payment:refund",
+      "subscription:read",
+      "subscription:manage",
+      "partner:read",
+      "partner:manage",
+      "partner:payout:approve",
+      "campaign:read",
+      "campaign:write",
+      "notification:read",
+      "notification:send",
+      "notification:template:write",
+      "store:read",
+      "store:write",
+      "blog:read",
+      "blog:write",
+      "blog:publish",
+      "analytics:read",
+      "diagnostics:read",
+      "diagnostics:write"
+    ];
+    exports2.PERMISSION_SET = new Set(exports2.ALL_PERMISSIONS);
+    function isPermissionString(value) {
+      return typeof value === "string" && exports2.PERMISSION_SET.has(value);
+    }
+    function parsePermissionString(value) {
+      if (!isPermissionString(value)) {
+        return null;
+      }
+      const colonIndex = value.indexOf(":");
+      const resource = value.slice(0, colonIndex);
+      const action = value.slice(colonIndex + 1);
+      return { resource, action };
+    }
+    exports2.SENSITIVE_MCP_RESOURCES = ["payment", "wallet"];
+    function isSensitiveMcpResource(resource) {
+      return resource === "payment" || resource === "wallet";
+    }
+    function isMcpEligiblePermission(permission) {
+      const parsed = parsePermissionString(permission);
+      if (!parsed)
+        return false;
+      return !isSensitiveMcpResource(parsed.resource);
+    }
+    exports2.MCP_ELIGIBLE_PERMISSIONS = exports2.ALL_PERMISSIONS.filter(isMcpEligiblePermission);
+    exports2.MCP_ELIGIBLE_PERMISSION_SET = new Set(exports2.MCP_ELIGIBLE_PERMISSIONS);
+    exports2.OFFLINE_ACCESS_SCOPE = "offline_access";
+    exports2.MCP_OAUTH_SCOPES = [
+      ...exports2.MCP_ELIGIBLE_PERMISSIONS,
+      exports2.OFFLINE_ACCESS_SCOPE
+    ];
+    function partitionMcpScopes(scopes) {
+      return {
+        permissionScopes: scopes.filter((scope) => scope !== exports2.OFFLINE_ACCESS_SCOPE),
+        offlineAccessRequested: scopes.includes(exports2.OFFLINE_ACCESS_SCOPE)
+      };
+    }
+  }
+});
+
+// src/bin.ts
+var bin_exports = {};
+__export(bin_exports, {
+  CLI_NAME: () => CLI_NAME,
+  CLI_VERSION: () => CLI_VERSION,
+  printHelp: () => printHelp,
+  runCli: () => runCli
+});
+module.exports = __toCommonJS(bin_exports);
+var import_node_util = require("util");
+
+// src/auth/device-flow.ts
+var import_node_child_process2 = require("child_process");
+var import_permissions = __toESM(require_permissions());
+
+// src/auth/http.ts
+var HttpError = class extends Error {
+  status;
+  data;
+  constructor(message, status, data) {
+    super(message);
+    this.name = "HttpError";
+    this.status = status;
+    this.data = data;
+  }
+};
+var DEFAULT_TIMEOUT_MS = 15e3;
+var DEFAULT_RETRIES = 2;
+async function sendRequest(url, options) {
+  const method = options?.method || "GET";
+  const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const maxRetries = options?.retries ?? DEFAULT_RETRIES;
+  const headers = {
+    Accept: "application/json",
+    ...options?.headers || {}
+  };
+  let serializedBody;
+  if (options?.body) {
+    if (typeof options.body === "string") {
+      serializedBody = options.body;
+    } else if (options.body instanceof URLSearchParams) {
+      serializedBody = options.body.toString();
+      if (!headers["Content-Type"]) {
+        headers["Content-Type"] = "application/x-www-form-urlencoded";
+      }
+    } else {
+      serializedBody = JSON.stringify(options.body);
+      if (!headers["Content-Type"]) {
+        headers["Content-Type"] = "application/json";
+      }
+    }
+  }
+  let attempt = 0;
+  let lastError = null;
+  while (attempt <= maxRetries) {
+    attempt++;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const fetchImpl = options?.fetchFn || fetch;
+      const res = await fetchImpl(url, {
+        method,
+        headers,
+        body: serializedBody,
+        signal: controller.signal
+      });
+      clearTimeout(timer);
+      const contentType = res.headers.get("content-type") || "";
+      let parsedData;
+      if (contentType.includes("application/json")) {
+        try {
+          parsedData = await res.json();
+        } catch {
+          parsedData = null;
+        }
+      } else {
+        parsedData = await res.text();
+      }
+      if (res.status >= 500 && res.status <= 504 && attempt <= maxRetries) {
+        const backoffMs = Math.min(1e3 * Math.pow(2, attempt - 1) + Math.random() * 200, 5e3);
+        await new Promise((resolve) => setTimeout(resolve, backoffMs));
+        continue;
+      }
+      return {
+        status: res.status,
+        ok: res.ok,
+        headers: res.headers,
+        data: parsedData
+      };
+    } catch (err) {
+      clearTimeout(timer);
+      const isAbort = err instanceof Error && err.name === "AbortError";
+      const errMsg = isAbort ? `Request timed out after ${timeoutMs}ms` : err instanceof Error ? err.message : String(err);
+      lastError = new Error(`Network request failed for ${method} ${url}: ${errMsg}`);
+      if (attempt <= maxRetries) {
+        const backoffMs = Math.min(500 * Math.pow(2, attempt - 1) + Math.random() * 200, 3e3);
+        await new Promise((resolve) => setTimeout(resolve, backoffMs));
+        continue;
+      }
+    }
+  }
+  throw lastError || new Error(`Network request failed after ${attempt} attempts`);
+}
+
+// src/auth/credentials-vault.ts
+var import_node_fs = __toESM(require("fs"));
+var import_node_path = __toESM(require("path"));
+var import_os = __toESM(require("os"));
+
+// src/auth/types.ts
+function isValidStoredCredentials(obj) {
+  if (!obj || typeof obj !== "object" || Array.isArray(obj)) {
+    return false;
+  }
+  const record = obj;
+  if (typeof record.serverUrl !== "string" || typeof record.clientId !== "string" || typeof record.accessToken !== "string" || typeof record.tokenType !== "string" || typeof record.expiresAt !== "number" || !Number.isFinite(record.expiresAt)) {
+    return false;
+  }
+  if (!("organizationId" in record) || record.organizationId !== null && typeof record.organizationId !== "string") {
+    return false;
+  }
+  if (record.refreshToken !== void 0 && typeof record.refreshToken !== "string") {
+    return false;
+  }
+  if (record.scope !== void 0 && typeof record.scope !== "string") {
+    return false;
+  }
+  if (record.resource !== void 0 && typeof record.resource !== "string") {
+    return false;
+  }
+  if (record.updatedAt !== void 0 && (typeof record.updatedAt !== "number" || !Number.isFinite(record.updatedAt))) {
+    return false;
+  }
+  return true;
+}
+function normalizeProfileKey(serverUrl, clientId) {
+  const cleanClient = (clientId || "").trim();
+  let urlToParse = (serverUrl || "").trim();
+  if (!/^https?:\/\//i.test(urlToParse)) {
+    urlToParse = `https://${urlToParse}`;
+  }
+  try {
+    const parsed = new URL(urlToParse);
+    const origin = parsed.origin.toLowerCase();
+    return `${origin}::${cleanClient}`;
+  } catch {
+    const cleanUrl = urlToParse.replace(/\/+$/, "").toLowerCase();
+    return `${cleanUrl}::${cleanClient}`;
+  }
+}
+function sanitizeSecretString(input, secrets) {
+  let sanitized = input;
+  for (const secret of secrets) {
+    if (secret && typeof secret === "string" && secret.length >= 4) {
+      sanitized = sanitized.split(secret).join("[REDACTED]");
+    }
+  }
+  return sanitized;
+}
+function isCredentialExpired(creds, skewSeconds = 60) {
+  if (!creds.expiresAt) {
+    return false;
+  }
+  const expiresAtMs = creds.expiresAt > 1e11 ? creds.expiresAt : creds.expiresAt * 1e3;
+  return Date.now() + skewSeconds * 1e3 >= expiresAtMs;
+}
+
+// src/auth/keychain.ts
+var import_node_child_process = require("child_process");
+var DefaultKeychainRunner = class {
+  defaultTimeoutMs;
+  constructor(defaultTimeoutMs = 5e3) {
+    this.defaultTimeoutMs = defaultTimeoutMs;
+  }
+  spawn(command, args, options) {
+    return new Promise((resolve) => {
+      let child;
+      try {
+        child = (0, import_node_child_process.spawn)(command, args, {
+          shell: false,
+          stdio: ["pipe", "pipe", "pipe"]
+        });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return resolve({ stdout: "", stderr: message, exitCode: -1 });
+      }
+      let stdout = "";
+      let stderr = "";
+      let isSettled = false;
+      const timeoutMs = options?.timeoutMs ?? this.defaultTimeoutMs;
+      const timer = setTimeout(() => {
+        if (!isSettled) {
+          isSettled = true;
+          try {
+            child.kill("SIGKILL");
+          } catch {
+          }
+          resolve({
+            stdout,
+            stderr: `Keychain operation timed out after ${timeoutMs}ms`,
+            exitCode: -1
+          });
+        }
+      }, timeoutMs);
+      child.stdout?.on("data", (chunk) => {
+        stdout += chunk.toString();
+      });
+      child.stderr?.on("data", (chunk) => {
+        stderr += chunk.toString();
+      });
+      child.on("error", (err) => {
+        stderr += err.message;
+      });
+      child.on("close", (code) => {
+        if (!isSettled) {
+          isSettled = true;
+          clearTimeout(timer);
+          resolve({
+            stdout,
+            stderr,
+            exitCode: code ?? -1
+          });
+        }
+      });
+      if (options?.input !== void 0 && child.stdin) {
+        try {
+          child.stdin.write(options.input);
+          child.stdin.end();
+        } catch {
+        }
+      }
+    });
+  }
+};
+var DEFAULT_KEYCHAIN_SERVICE = "iwas-cli";
+var KeychainService = class {
+  service;
+  runner;
+  platform;
+  constructor(options) {
+    this.service = options?.serviceName || DEFAULT_KEYCHAIN_SERVICE;
+    this.runner = options?.runner || new DefaultKeychainRunner();
+    this.platform = options?.platform || process.platform;
+  }
+  availableCache = null;
+  /**
+   * Returns the configured OS platform.
+   */
+  getPlatform() {
+    return this.platform;
+  }
+  /**
+   * Probes whether the host environment has an operable keychain utility.
+   * Results are cached when available to avoid unnecessary subprocess spawns (n7 fix).
+   */
+  async isAvailable(forceProbe = false) {
+    if (!forceProbe && this.availableCache === true) {
+      return true;
+    }
+    if (this.platform === "darwin") {
+      const res = await this.runner.spawn("/usr/bin/security", ["help"]);
+      const isAvail = res.exitCode === 0 || res.stdout.includes("security") || res.stderr.includes("security");
+      if (isAvail) {
+        this.availableCache = true;
+      }
+      return isAvail;
+    }
+    if (this.platform === "linux") {
+      const res = await this.runner.spawn("which", ["secret-tool"]);
+      const isAvail = res.exitCode === 0;
+      if (isAvail) {
+        this.availableCache = true;
+      }
+      return isAvail;
+    }
+    return false;
+  }
+  /**
+   * Clears the cached isAvailable probe result. Useful for testing and environment shifts.
+   */
+  clearAvailabilityCache() {
+    this.availableCache = null;
+  }
+  /**
+   * Retrieves a secret password string by account identifier.
+   */
+  async getSecret(account) {
+    if (this.platform === "darwin") {
+      const res = await this.runner.spawn("/usr/bin/security", [
+        "find-generic-password",
+        "-s",
+        this.service,
+        "-a",
+        account,
+        "-w"
+      ]);
+      if (res.exitCode === 0) {
+        const raw = res.stdout.trim();
+        if (raw.length > 0 && raw.length % 2 === 0 && /^[0-9a-fA-F]+$/.test(raw)) {
+          if (raw.startsWith("7b") || raw.startsWith("7B") || raw.startsWith("5b") || raw.startsWith("5B")) {
+            try {
+              const decoded = Buffer.from(raw, "hex").toString("utf8");
+              if (!decoded.includes("\uFFFD")) {
+                return decoded;
+              }
+            } catch {
+            }
+          }
+        }
+        return raw;
+      }
+      if (res.exitCode === 44 || res.stderr.includes("could not be found") || res.stderr.includes("The specified item could not be found")) {
+        return null;
+      }
+      throw new Error(`Keychain read failed: ${res.stderr.trim() || `exit code ${res.exitCode}`}`);
+    }
+    if (this.platform === "linux") {
+      const res = await this.runner.spawn("secret-tool", [
+        "lookup",
+        "service",
+        this.service,
+        "account",
+        account
+      ]);
+      if (res.exitCode === 0) {
+        return res.stdout.length > 0 ? res.stdout.trim() : null;
+      }
+      const err = res.stderr.trim();
+      if (res.exitCode === 1 && (err === "" || err.toLowerCase().includes("not found") || err.toLowerCase().includes("no such secret"))) {
+        return null;
+      }
+      throw new Error(`Secret-tool read failed: ${err || `exit code ${res.exitCode}`}`);
+    }
+    throw new Error(`OS keychain not supported on platform: ${this.platform}`);
+  }
+  /**
+   * Stores a secret password under the given account identifier.
+   */
+  async setSecret(account, secret, label) {
+    const itemLabel = label || `${this.service} (${account})`;
+    const secretsToRedact = [secret];
+    try {
+      const parsed = JSON.parse(secret);
+      if (typeof parsed === "object" && parsed !== null) {
+        for (const val of Object.values(parsed)) {
+          if (typeof val === "string" && val.length >= 4) {
+            secretsToRedact.push(val);
+          }
+        }
+      }
+    } catch {
+    }
+    if (this.platform === "darwin") {
+      const res = await this.runner.spawn("/usr/bin/security", [
+        "add-generic-password",
+        "-U",
+        "-s",
+        this.service,
+        "-a",
+        account,
+        "-l",
+        itemLabel,
+        "-w",
+        secret
+      ]);
+      if (res.exitCode !== 0) {
+        const errorMsg = sanitizeSecretString(res.stderr.trim(), secretsToRedact);
+        throw new Error(`Keychain write failed: ${errorMsg || `exit code ${res.exitCode}`}`);
+      }
+      return;
+    }
+    if (this.platform === "linux") {
+      const res = await this.runner.spawn(
+        "secret-tool",
+        ["store", `--label=${itemLabel}`, "service", this.service, "account", account],
+        { input: secret }
+      );
+      if (res.exitCode !== 0) {
+        const errorMsg = sanitizeSecretString(res.stderr.trim(), secretsToRedact);
+        throw new Error(`Secret-tool write failed: ${errorMsg || `exit code ${res.exitCode}`}`);
+      }
+      return;
+    }
+    throw new Error(`OS keychain not supported on platform: ${this.platform}`);
+  }
+  /**
+   * Deletes a secret from the keychain. Operation is strictly idempotent.
+   */
+  async deleteSecret(account) {
+    if (this.platform === "darwin") {
+      const res = await this.runner.spawn("/usr/bin/security", [
+        "delete-generic-password",
+        "-s",
+        this.service,
+        "-a",
+        account
+      ]);
+      if (res.exitCode === 0 || res.exitCode === 44 || res.stderr.includes("could not be found")) {
+        return;
+      }
+      throw new Error(`Keychain delete failed: ${res.stderr.trim() || `exit code ${res.exitCode}`}`);
+    }
+    if (this.platform === "linux") {
+      const res = await this.runner.spawn("secret-tool", [
+        "clear",
+        "service",
+        this.service,
+        "account",
+        account
+      ]);
+      if (res.exitCode === 0 || res.exitCode === 1) {
+        return;
+      }
+      throw new Error(`Secret-tool clear failed: ${res.stderr.trim() || `exit code ${res.exitCode}`}`);
+    }
+    throw new Error(`OS keychain not supported on platform: ${this.platform}`);
+  }
+};
+
+// src/auth/credentials-vault.ts
+var KEYCHAIN_PROFILES_INDEX_ACCOUNT = "__profiles__";
+var CredentialVault = class {
+  vaultType;
+  configDir;
+  credentialsFilePath;
+  keychain;
+  constructor(options) {
+    const rawEnvVault = process.env.IWAS_MCP_VAULT;
+    if (rawEnvVault && !["auto", "keychain", "file"].includes(rawEnvVault)) {
+      throw new Error(
+        `Invalid IWAS_MCP_VAULT value: "${rawEnvVault}". Supported values are "auto", "keychain", or "file".`
+      );
+    }
+    const envVault = rawEnvVault;
+    this.vaultType = options?.vaultType || envVault || "auto";
+    const baseConfigDir = options?.configDir || process.env.XDG_CONFIG_HOME || import_node_path.default.join(import_os.default.homedir(), ".config");
+    this.configDir = options?.configDir ? options.configDir : import_node_path.default.join(baseConfigDir, "iwas");
+    this.credentialsFilePath = import_node_path.default.join(this.configDir, "credentials.json");
+    this.keychain = options?.keychainService || new KeychainService({
+      serviceName: options?.serviceName || DEFAULT_KEYCHAIN_SERVICE,
+      runner: options?.keychainRunner
+    });
+  }
+  /**
+   * Returns the configuration directory for this vault (~/.config/iwas).
+   */
+  getConfigDir() {
+    return this.configDir;
+  }
+  /**
+   * Returns the credentials file path (~/.config/iwas/credentials.json).
+   */
+  getCredentialsFilePath() {
+    return this.credentialsFilePath;
+  }
+  /**
+   * Returns the resolved vault mode: 'keychain' or 'file'.
+   * In strict 'keychain' mode, throws if OS keychain is unavailable.
+   */
+  async getEffectiveBackend() {
+    if (this.vaultType === "file") {
+      return "file";
+    }
+    const available = await this.keychain.isAvailable().catch(() => false);
+    const platform = this.keychain.getPlatform();
+    if (this.vaultType === "keychain") {
+      if (!available) {
+        throw new Error(
+          `Keychain vault requested (IWAS_MCP_VAULT="keychain") but OS keychain is unavailable on platform: ${platform}`
+        );
+      }
+      return "keychain";
+    }
+    return available ? "keychain" : "file";
+  }
+  /**
+   * Retrieves stored credentials by profile key.
+   * In auto mode, checks keychain first; falls back to file if missing or failed.
+   * Compares timestamps if both exist and migrates newer file credentials to keychain (Medium fix).
+   */
+  async load(profileKey) {
+    const backend = await this.getEffectiveBackend();
+    if (backend === "keychain") {
+      let kcCreds = null;
+      try {
+        const raw = await this.keychain.getSecret(profileKey);
+        if (raw) {
+          try {
+            const parsed = JSON.parse(raw);
+            if (isValidStoredCredentials(parsed)) {
+              kcCreds = parsed;
+            } else if (this.vaultType === "keychain") {
+              throw new Error(`Corrupt credentials stored in keychain for profile: ${profileKey}`);
+            }
+          } catch (parseErr) {
+            if (this.vaultType === "keychain") {
+              const msg = parseErr instanceof Error ? parseErr.message : String(parseErr);
+              throw new Error(`Corrupt credentials JSON in keychain for profile ${profileKey}: ${msg}`);
+            }
+          }
+        }
+      } catch (err) {
+        if (this.vaultType === "keychain") {
+          throw err;
+        }
+      }
+      if (this.vaultType === "keychain") {
+        return kcCreds;
+      }
+      const fileCreds = this.loadFromFile(profileKey);
+      if (!kcCreds) {
+        if (fileCreds) {
+          try {
+            await this.keychain.setSecret(
+              profileKey,
+              JSON.stringify(fileCreds),
+              `IWAS MCP Profile (${profileKey})`
+            );
+            await this.addProfileToKeychainIndex(profileKey);
+            this.deleteFromFile(profileKey);
+          } catch {
+          }
+        }
+        return fileCreds;
+      }
+      if (!fileCreds) {
+        return kcCreds;
+      }
+      const kcTime = kcCreds.updatedAt ?? kcCreds.expiresAt ?? 0;
+      const fileTime = fileCreds.updatedAt ?? fileCreds.expiresAt ?? 0;
+      if (fileTime > kcTime) {
+        try {
+          await this.keychain.setSecret(
+            profileKey,
+            JSON.stringify(fileCreds),
+            `IWAS MCP Profile (${profileKey})`
+          );
+          await this.addProfileToKeychainIndex(profileKey);
+          this.deleteFromFile(profileKey);
+        } catch {
+        }
+        return fileCreds;
+      } else {
+        this.deleteFromFile(profileKey);
+        return kcCreds;
+      }
+    }
+    return this.loadFromFile(profileKey);
+  }
+  /**
+   * Persists credentials for the given profile key.
+   * When saving to keychain, purges any stale copy from the file fallback (Major 1).
+   */
+  async save(profileKey, credentials) {
+    const backend = await this.getEffectiveBackend();
+    const toSave = {
+      ...credentials,
+      updatedAt: credentials.updatedAt ?? Date.now()
+    };
+    if (backend === "keychain") {
+      let secretSaved = false;
+      try {
+        const secret = JSON.stringify(toSave);
+        await this.keychain.setSecret(
+          profileKey,
+          secret,
+          `IWAS MCP Profile (${profileKey})`
+        );
+        secretSaved = true;
+        try {
+          await this.addProfileToKeychainIndex(profileKey);
+        } catch (indexErr) {
+          const message = indexErr instanceof Error ? indexErr.message : String(indexErr);
+          const sanitized = sanitizeSecretString(message, [
+            toSave.accessToken,
+            toSave.refreshToken
+          ]);
+          throw new Error(`Keychain index update failed: ${sanitized}`);
+        }
+        this.deleteFromFile(profileKey);
+        return;
+      } catch (err) {
+        if (this.vaultType === "keychain" || secretSaved) {
+          const message = err instanceof Error ? err.message : String(err);
+          const sanitized = sanitizeSecretString(message, [
+            toSave.accessToken,
+            toSave.refreshToken
+          ]);
+          throw err instanceof Error && err.message.startsWith("Keychain") ? err : new Error(`Keychain save failed: ${sanitized}`);
+        }
+      }
+    }
+    this.saveToFile(profileKey, toSave);
+  }
+  /**
+   * Removes credentials for the given profile key.
+   * Cleanses BOTH Keychain and File fallback to prevent plaintext leakage (Major 1).
+   * In auto mode, throws if keychain is available but secret deletion fails (Major fix).
+   */
+  async delete(profileKey) {
+    let keychainError = null;
+    let isAvailable = false;
+    if (this.vaultType === "file") {
+      this.deleteFromFile(profileKey);
+      return;
+    }
+    try {
+      isAvailable = await this.keychain.isAvailable().catch(() => false);
+      if (this.vaultType === "keychain" && !isAvailable) {
+        throw new Error(
+          `Keychain vault requested (IWAS_MCP_VAULT="keychain") but OS keychain is unavailable on platform: ${this.keychain.getPlatform()}`
+        );
+      }
+      if (isAvailable) {
+        await this.keychain.deleteSecret(profileKey);
+        await this.removeProfileFromKeychainIndex(profileKey);
+      }
+    } catch (err) {
+      keychainError = err;
+    }
+    this.deleteFromFile(profileKey);
+    if (keychainError) {
+      if (this.vaultType === "keychain" || this.vaultType === "auto" && isAvailable) {
+        throw keychainError;
+      }
+    }
+  }
+  /**
+   * Lists all stored profile keys.
+   * In auto mode, merges profiles from both Keychain and File.
+   */
+  async listProfiles() {
+    if (this.vaultType === "file") {
+      return this.listProfilesFromFile();
+    }
+    if (this.vaultType === "keychain") {
+      return this.readKeychainIndex();
+    }
+    const profiles = /* @__PURE__ */ new Set();
+    try {
+      const isAvailable = await this.keychain.isAvailable();
+      if (isAvailable) {
+        const kcProfiles = await this.readKeychainIndex();
+        for (const p of kcProfiles) {
+          profiles.add(p);
+        }
+      }
+    } catch {
+    }
+    for (const p of this.listProfilesFromFile()) {
+      profiles.add(p);
+    }
+    return Array.from(profiles);
+  }
+  // --- Internal Keychain Index (Major 2: Safe read & abort on error) ---
+  async readKeychainIndex() {
+    const rawIndex = await this.keychain.getSecret(KEYCHAIN_PROFILES_INDEX_ACCOUNT);
+    if (!rawIndex) {
+      return [];
+    }
+    try {
+      const parsed = JSON.parse(rawIndex);
+      return Array.isArray(parsed) ? parsed.filter((item) => typeof item === "string") : [];
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw new Error(`Corrupt keychain profile index at ${KEYCHAIN_PROFILES_INDEX_ACCOUNT}: ${message}`);
+    }
+  }
+  async addProfileToKeychainIndex(profileKey) {
+    const current = await this.readKeychainIndex();
+    if (!current.includes(profileKey)) {
+      current.push(profileKey);
+      await this.keychain.setSecret(
+        KEYCHAIN_PROFILES_INDEX_ACCOUNT,
+        JSON.stringify(current),
+        "IWAS MCP Profiles Index"
+      );
+    }
+  }
+  async removeProfileFromKeychainIndex(profileKey) {
+    const current = await this.readKeychainIndex();
+    if (current.includes(profileKey)) {
+      const updated = current.filter((k) => k !== profileKey);
+      await this.keychain.setSecret(
+        KEYCHAIN_PROFILES_INDEX_ACCOUNT,
+        JSON.stringify(updated),
+        "IWAS MCP Profiles Index"
+      );
+    }
+  }
+  // --- Internal File Storage Backend (dir 0700, file 0600, atomic replace) ---
+  ensureConfigDirectory() {
+    if (!import_node_fs.default.existsSync(this.configDir)) {
+      import_node_fs.default.mkdirSync(this.configDir, { recursive: true, mode: 448 });
+    }
+    try {
+      import_node_fs.default.chmodSync(this.configDir, 448);
+    } catch {
+    }
+  }
+  readAllFromFile() {
+    if (!import_node_fs.default.existsSync(this.credentialsFilePath)) {
+      return {};
+    }
+    if (process.platform !== "win32") {
+      try {
+        import_node_fs.default.chmodSync(this.credentialsFilePath, 384);
+      } catch {
+      }
+    }
+    const content = import_node_fs.default.readFileSync(this.credentialsFilePath, "utf8").trim();
+    if (!content) {
+      return {};
+    }
+    try {
+      const parsed = JSON.parse(content);
+      if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error("Root credentials object must be a JSON record");
+      }
+      for (const [key, item] of Object.entries(parsed)) {
+        if (!isValidStoredCredentials(item)) {
+          throw new Error(`Profile "${key}" contains invalid or missing credential fields`);
+        }
+      }
+      return parsed;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw new Error(
+        `Corrupt credentials file at ${this.credentialsFilePath}: ${message}. Will not overwrite.`
+      );
+    }
+  }
+  writeAllToFile(data) {
+    this.ensureConfigDirectory();
+    const content = JSON.stringify(data, null, 2) + "\n";
+    const tmpFilePath = import_node_path.default.join(
+      this.configDir,
+      `.credentials.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`
+    );
+    let fd = null;
+    try {
+      fd = import_node_fs.default.openSync(tmpFilePath, "w", 384);
+      import_node_fs.default.writeSync(fd, content, void 0, "utf8");
+      import_node_fs.default.fsyncSync(fd);
+      import_node_fs.default.closeSync(fd);
+      fd = null;
+      try {
+        import_node_fs.default.chmodSync(tmpFilePath, 384);
+      } catch {
+      }
+      import_node_fs.default.renameSync(tmpFilePath, this.credentialsFilePath);
+      try {
+        import_node_fs.default.chmodSync(this.credentialsFilePath, 384);
+      } catch {
+      }
+      if (process.platform !== "win32") {
+        try {
+          const dirFd = import_node_fs.default.openSync(this.configDir, "r");
+          import_node_fs.default.fsyncSync(dirFd);
+          import_node_fs.default.closeSync(dirFd);
+        } catch {
+        }
+      }
+    } catch (err) {
+      if (fd !== null) {
+        try {
+          import_node_fs.default.closeSync(fd);
+        } catch {
+        }
+      }
+      if (import_node_fs.default.existsSync(tmpFilePath)) {
+        try {
+          import_node_fs.default.unlinkSync(tmpFilePath);
+        } catch {
+        }
+      }
+      throw err;
+    }
+  }
+  loadFromFile(profileKey) {
+    const all = this.readAllFromFile();
+    return all[profileKey] ?? null;
+  }
+  saveToFile(profileKey, credentials) {
+    const all = this.readAllFromFile();
+    all[profileKey] = credentials;
+    this.writeAllToFile(all);
+  }
+  deleteFromFile(profileKey) {
+    if (!import_node_fs.default.existsSync(this.credentialsFilePath)) {
+      return;
+    }
+    const all = this.readAllFromFile();
+    if (profileKey in all) {
+      delete all[profileKey];
+      this.writeAllToFile(all);
+    }
+  }
+  listProfilesFromFile() {
+    if (!import_node_fs.default.existsSync(this.credentialsFilePath)) {
+      return [];
+    }
+    const all = this.readAllFromFile();
+    return Object.keys(all);
+  }
+};
+
+// src/auth/logout.ts
+async function executeLogout(options) {
+  const log = options?.logger || ((msg) => process.stdout.write(`${msg}
+`));
+  const errLog = options?.errorLogger || ((msg) => process.stderr.write(`${msg}
+`));
+  const serverUrl = resolveAuthServerUrl(options?.server);
+  const clientId = (options?.clientId || DEFAULT_CLI_CLIENT_ID).trim();
+  const profileKey = normalizeProfileKey(serverUrl, clientId);
+  const vault = options?.vault || new CredentialVault();
+  const force = options?.force === true;
+  const credentials = await vault.load(profileKey);
+  if (!credentials) {
+    const result2 = {
+      success: true,
+      profileKey,
+      serverRevoked: false,
+      refreshTokenRevoked: false,
+      localCleared: false,
+      message: `No stored credentials found for profile: ${profileKey}`
+    };
+    if (options?.json) {
+      log(
+        JSON.stringify({
+          event: "logout",
+          success: true,
+          loggedOut: true,
+          profileKey,
+          serverRevoked: false,
+          refreshTokenRevoked: false,
+          localCleared: false,
+          message: result2.message
+        })
+      );
+    } else {
+      log(`\u2139\uFE0F  No stored credentials found for profile: ${profileKey}`);
+    }
+    return result2;
+  }
+  let serverRevoked = false;
+  let serverError = null;
+  const sessionLogoutUrl = `${serverUrl.replace(/\/+$/, "")}/api/v1/mcp-session/logout`;
+  try {
+    const authScheme = credentials.tokenType || "Bearer";
+    const res = await sendRequest(sessionLogoutUrl, {
+      method: "POST",
+      headers: {
+        Authorization: `${authScheme} ${credentials.accessToken}`
+      },
+      fetchFn: options?.fetchFn
+    });
+    if (res.status === 204 || res.status === 200) {
+      serverRevoked = true;
+    } else if (res.status === 401 || res.status === 403) {
+      serverRevoked = true;
+    } else if (res.status === 400) {
+      const data = res.data;
+      throw new Error(data?.message || "Server rejected logout request (HTTP 400).");
+    } else {
+      throw new HttpError(
+        `Server returned status ${res.status} during logout`,
+        res.status,
+        res.data
+      );
+    }
+  } catch (err) {
+    serverError = err instanceof Error ? err : new Error(String(err));
+  }
+  if (serverError && !force) {
+    const errorMsg = `Server revocation failed: ${serverError.message}. Local credentials preserved. Use --force to clear local credentials anyway if the server is permanently offline.`;
+    throw new Error(errorMsg);
+  }
+  let refreshTokenRevoked = false;
+  if (credentials.refreshToken) {
+    try {
+      const revokeUrl = `${serverUrl.replace(/\/+$/, "")}/api/auth/oauth2/revoke`;
+      const body = new URLSearchParams({
+        token: credentials.refreshToken,
+        token_type_hint: "refresh_token",
+        client_id: clientId
+      });
+      const res = await sendRequest(revokeUrl, {
+        method: "POST",
+        body,
+        fetchFn: options?.fetchFn
+      });
+      if (res.ok || res.status === 200 || res.status === 204 || res.status === 401 || res.status === 400) {
+        refreshTokenRevoked = true;
+      }
+    } catch {
+    }
+  }
+  await vault.delete(profileKey);
+  const result = {
+    success: true,
+    profileKey,
+    serverRevoked,
+    refreshTokenRevoked,
+    localCleared: true,
+    message: serverError ? `Local credentials cleared with --force (server unreachable: ${serverError.message})` : "Successfully logged out and revoked all grants server-side"
+  };
+  if (options?.json) {
+    log(
+      JSON.stringify({
+        event: "logout",
+        success: true,
+        loggedOut: true,
+        profileKey,
+        serverRevoked,
+        refreshTokenRevoked,
+        localCleared: true,
+        forced: force && !!serverError
+      })
+    );
+  } else {
+    if (serverError) {
+      errLog(`\u26A0\uFE0F  Warning: Server revocation failed (${serverError.message})`);
+      log(`\u2705 Local credentials cleared for profile: ${profileKey} (--force)
+`);
+    } else {
+      log(`
+\u2705 Successfully logged out from profile: ${profileKey}`);
+      log("   \u2022 Server session & OAuth grants: Revoked");
+      log("   \u2022 Local credentials: Removed\n");
+    }
+  }
+  return result;
+}
+
+// src/auth/device-flow.ts
+var DEFAULT_CLI_CLIENT_ID = "iwas-cli";
+var DEFAULT_SERVER_URL = "https://getiwas.com";
+var DEFAULT_READ_ONLY_SCOPES = import_permissions.MCP_ELIGIBLE_PERMISSIONS.filter(
+  (perm) => perm.endsWith(":read")
+);
+var DEFAULT_SCOPES = [
+  ...DEFAULT_READ_ONLY_SCOPES,
+  import_permissions.OFFLINE_ACCESS_SCOPE
+].join(" ");
+var DEVICE_CODE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
+function validateScopes(scopesString) {
+  const requested = scopesString.split(/\s+/).filter(Boolean);
+  if (requested.length === 0) {
+    return {
+      valid: false,
+      invalidScopes: [],
+      error: "At least one OAuth scope must be requested."
+    };
+  }
+  const allowedSet = new Set(import_permissions.MCP_OAUTH_SCOPES);
+  const invalidScopes = requested.filter((s) => !allowedSet.has(s));
+  if (invalidScopes.length > 0) {
+    return {
+      valid: false,
+      invalidScopes,
+      error: `Invalid OAuth scope(s) requested: [${invalidScopes.join(", ")}]. Supported scopes are: [${import_permissions.MCP_OAUTH_SCOPES.join(", ")}]`
+    };
+  }
+  const capabilityScopes = requested.filter((s) => s !== import_permissions.OFFLINE_ACCESS_SCOPE);
+  if (capabilityScopes.length === 0) {
+    return {
+      valid: false,
+      invalidScopes: [],
+      error: "At least one MCP capability scope besides offline_access must be requested."
+    };
+  }
+  return { valid: true, invalidScopes: [] };
+}
+function isLocalhost(hostname) {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1" || hostname === "[::1]";
+}
+function resolveAuthServerUrl(input) {
+  let urlStr = (input || process.env.IWAS_SERVER_URL || DEFAULT_SERVER_URL).trim();
+  urlStr = urlStr.replace(/\/+$/, "");
+  if (urlStr.toLowerCase().endsWith("/mcp")) {
+    throw new Error(
+      `Invalid --server value: "${urlStr}". The server argument must be the auth/web origin (e.g. "https://getiwas.com"), not the MCP resource endpoint. Use --resource for "${urlStr}".`
+    );
+  }
+  if (!/^https?:\/\//i.test(urlStr)) {
+    urlStr = `https://${urlStr}`;
+  }
+  let parsed;
+  try {
+    parsed = new URL(urlStr);
+  } catch {
+    throw new Error(`Invalid server URL: "${urlStr}"`);
+  }
+  if (parsed.pathname && parsed.pathname !== "/") {
+    const originStr = parsed.origin;
+    const label = input ? `--server value: "${input}"` : `IWAS_SERVER_URL: "${urlStr}"`;
+    throw new Error(
+      `Invalid ${label}. The server argument must be an origin without a path component (e.g. "${originStr}").`
+    );
+  }
+  if (!isLocalhost(parsed.hostname) && parsed.protocol !== "https:") {
+    throw new Error(
+      `Insecure server protocol: "${urlStr}". Non-localhost servers require HTTPS per OAuth 2.1 specifications.`
+    );
+  }
+  return parsed.origin.toLowerCase();
+}
+function resolveMcpResourceUrl(serverUrl, input) {
+  if (input && input.trim()) {
+    let clean = input.trim();
+    if (!/^https?:\/\//i.test(clean)) {
+      const isLoopbackCandidate = clean.startsWith("localhost") || clean.startsWith("127.0.0.1") || clean.startsWith("[::1]") || clean.startsWith("::1");
+      clean = isLoopbackCandidate ? `http://${clean}` : `https://${clean}`;
+    }
+    let parsed;
+    try {
+      parsed = new URL(clean);
+    } catch {
+      throw new Error(`Invalid resource URL: "${clean}"`);
+    }
+    if (!isLocalhost(parsed.hostname) && parsed.protocol !== "https:") {
+      throw new Error(
+        `Insecure resource protocol: "${clean}". Non-localhost resource endpoints require HTTPS.`
+      );
+    }
+    return parsed.href.replace(/\/+$/, "");
+  }
+  return `${serverUrl}/mcp`;
+}
+function decodeJwtPayload(token) {
+  const parts = token.split(".");
+  if (parts.length !== 3) {
+    return {};
+  }
+  try {
+    const jsonStr = Buffer.from(parts[1], "base64url").toString("utf8");
+    const parsed = JSON.parse(jsonStr);
+    return typeof parsed === "object" && parsed !== null ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+function openBrowser(url, spawnFn = import_node_child_process2.spawn, onWarning) {
+  try {
+    let parsed;
+    try {
+      parsed = new URL(url);
+    } catch {
+      onWarning?.(`Invalid verification URL: "${url}". Please open manually.`);
+      return false;
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      onWarning?.(`Insecure verification URL protocol: "${parsed.protocol}". Expected http: or https:.`);
+      return false;
+    }
+    const platform = process.platform;
+    let child;
+    if (platform === "darwin") {
+      child = spawnFn("open", [parsed.href], { detached: true, stdio: "ignore" });
+    } else if (platform === "win32") {
+      child = spawnFn("explorer.exe", [parsed.href], { detached: true, stdio: "ignore" });
+    } else {
+      child = spawnFn("xdg-open", [parsed.href], { detached: true, stdio: "ignore" });
+    }
+    child.on("error", (err) => {
+      const msg = err instanceof Error ? err.message : String(err);
+      onWarning?.(`Could not launch browser automatically (${msg}). Please open the verification URL manually.`);
+    });
+    child.unref();
+    return true;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    onWarning?.(`Could not launch browser (${msg}). Please open the verification URL manually.`);
+    return false;
+  }
+}
+async function requestDeviceCode(serverUrl, params) {
+  const endpoint = `${serverUrl}/api/auth/device/code`;
+  const res = await sendRequest(endpoint, {
+    method: "POST",
+    body: {
+      client_id: params.clientId,
+      scope: params.scope,
+      resource: params.resource
+    },
+    retries: 0
+    // Zero retries to guarantee single-use device_code creation
+  });
+  if (!res.ok || !res.data || typeof res.data !== "object") {
+    throw new HttpError(
+      `Failed to initiate device authorization with ${endpoint}: HTTP ${res.status}`,
+      res.status,
+      res.data
+    );
+  }
+  const data = res.data;
+  if (!data.device_code || !data.user_code || !data.verification_uri) {
+    throw new Error(
+      `Malformed device code response from ${endpoint}: missing required RFC 8628 fields`
+    );
+  }
+  return {
+    device_code: data.device_code,
+    user_code: data.user_code,
+    verification_uri: data.verification_uri,
+    verification_uri_complete: data.verification_uri_complete || `${data.verification_uri}?user_code=${encodeURIComponent(data.user_code)}`,
+    expires_in: data.expires_in || 600,
+    interval: data.interval || 5
+  };
+}
+async function pollDeviceToken(serverUrl, params, onPollTick) {
+  const tokenEndpoint = `${serverUrl}/api/auth/oauth2/token`;
+  let intervalSec = Math.max(params.initialInterval || 5, 1);
+  const timeoutMs = params.timeoutMs || 3e5;
+  const startTime = Date.now();
+  while (Date.now() - startTime < timeoutMs) {
+    await new Promise((resolve) => setTimeout(resolve, intervalSec * 1e3));
+    if (Date.now() - startTime >= timeoutMs) {
+      break;
+    }
+    onPollTick?.("polling");
+    const formBody = new URLSearchParams({
+      grant_type: DEVICE_CODE_GRANT_TYPE,
+      client_id: params.clientId,
+      device_code: params.deviceCode,
+      resource: params.resource
+    });
+    const res = await sendRequest(
+      tokenEndpoint,
+      {
+        method: "POST",
+        body: formBody,
+        retries: 0
+        // Zero retries to guarantee single-use device_code is never double-consumed
+      }
+    );
+    if (res.status === 200) {
+      const tokenData = res.data;
+      if (!tokenData.access_token) {
+        throw new Error("Token endpoint returned HTTP 200 without access_token");
+      }
+      return tokenData;
+    }
+    if (res.status === 429) {
+      const retryAfterHeader = res.headers?.get?.("retry-after");
+      let retrySeconds = intervalSec + 5;
+      if (retryAfterHeader) {
+        const parsedSec = parseInt(retryAfterHeader, 10);
+        if (!isNaN(parsedSec) && parsedSec > 0) {
+          retrySeconds = parsedSec;
+        } else {
+          const parsedDate = Date.parse(retryAfterHeader);
+          if (!isNaN(parsedDate)) {
+            const diffSec = Math.ceil((parsedDate - Date.now()) / 1e3);
+            if (diffSec > 0) {
+              retrySeconds = diffSec;
+            }
+          }
+        }
+      }
+      const remainingMs = Math.max(0, timeoutMs - (Date.now() - startTime));
+      const remainingSec = Math.ceil(remainingMs / 1e3);
+      intervalSec = remainingSec > 0 ? Math.min(retrySeconds, 60, remainingSec) : 0;
+      onPollTick?.(`slow_down (rate_limited, retry-after: ${intervalSec}s)`);
+      continue;
+    }
+    const errorData = res.data || {};
+    const errorCode = errorData.error || "unknown_error";
+    const errorDesc = errorData.error_description || errorCode;
+    switch (errorCode) {
+      case "authorization_pending":
+        continue;
+      case "slow_down":
+        intervalSec += 5;
+        onPollTick?.(`slow_down (interval: ${intervalSec}s)`);
+        continue;
+      case "expired_token":
+        throw new Error(
+          "Device code has expired. Please run `iwas login` again to obtain a new code."
+        );
+      case "access_denied":
+        throw new Error("Authorization was denied by the user.");
+      case "invalid_grant":
+        throw new Error(
+          `Invalid grant: ${errorDesc}. The device code may have already been used or revoked.`
+        );
+      case "invalid_client":
+        throw new Error(`Invalid OAuth client: ${errorDesc}. Check your --client-id.`);
+      default:
+        if (res.status >= 500) {
+          intervalSec = Math.min(intervalSec + 2, 30);
+          continue;
+        }
+        throw new Error(`Device authorization failed: ${errorDesc} (HTTP ${res.status})`);
+    }
+  }
+  throw new Error("Device login timed out waiting for user authorization.");
+}
+async function executeLogin(options) {
+  const log = options?.logger || ((msg) => process.stdout.write(`${msg}
+`));
+  const errLog = options?.errorLogger || ((msg) => process.stderr.write(`${msg}
+`));
+  const serverUrl = resolveAuthServerUrl(options?.server);
+  const resourceUrl = resolveMcpResourceUrl(serverUrl, options?.resource);
+  const clientId = (options?.clientId || DEFAULT_CLI_CLIENT_ID).trim();
+  const scopes = (options?.scopes || DEFAULT_SCOPES).trim();
+  const vault = options?.vault || new CredentialVault();
+  const scopeValidation = validateScopes(scopes);
+  if (!scopeValidation.valid) {
+    throw new Error(scopeValidation.error || "Invalid OAuth scopes requested.");
+  }
+  const authResponse = await requestDeviceCode(serverUrl, {
+    clientId,
+    scope: scopes,
+    resource: resourceUrl
+  });
+  if (options?.json) {
+    const initEvent = {
+      event: "device_authorization",
+      user_code: authResponse.user_code,
+      verification_uri: authResponse.verification_uri,
+      verification_uri_complete: authResponse.verification_uri_complete,
+      expires_in: authResponse.expires_in,
+      interval: authResponse.interval
+    };
+    log(JSON.stringify(initEvent));
+    errLog(`
+\u{1F449} USER CODE: ${authResponse.user_code}`);
+    errLog(`\u{1F517} To verify, open: ${authResponse.verification_uri_complete}
+`);
+  } else {
+    log("\n============================================================");
+    log("               IWAS MCP Device Authorization                ");
+    log("============================================================\n");
+    log(`First, enter this code on the verification page:`);
+    log(`
+    \u{1F449}  USER CODE:  \x1B[1m\x1B[32m${authResponse.user_code}\x1B[0m
+`);
+    log(`To verify, open:`);
+    log(`    \u{1F517}  ${authResponse.verification_uri_complete}
+`);
+    log("Waiting for approval in browser...");
+  }
+  const spawnFn = options?.spawnFn || import_node_child_process2.spawn;
+  const opener = options?.browserOpener || ((url) => openBrowser(url, spawnFn, (warning) => {
+    if (!options?.json) {
+      log(`\u26A0\uFE0F  ${warning}`);
+    } else {
+      errLog(`\u26A0\uFE0F  ${warning}`);
+    }
+  }));
+  if (!options?.noBrowser) {
+    opener(authResponse.verification_uri_complete);
+  }
+  const pollTimeoutMs = options?.pollTimeoutMs ?? authResponse.expires_in * 1e3;
+  const tokenResponse = await pollDeviceToken(
+    serverUrl,
+    {
+      clientId,
+      deviceCode: authResponse.device_code,
+      resource: resourceUrl,
+      initialInterval: authResponse.interval,
+      timeoutMs: pollTimeoutMs
+    },
+    (status) => {
+      if (!options?.json && status.startsWith("slow_down")) {
+        log(`Rate limit reached: slowing poll interval.`);
+      }
+    }
+  );
+  const payload = decodeJwtPayload(tokenResponse.access_token);
+  if (!payload || Object.keys(payload).length === 0) {
+    throw new Error(
+      "Server returned an opaque or non-JWT access token. Expected a JWT access token targeted for MCP resource."
+    );
+  }
+  const tokenAud = Array.isArray(payload.aud) ? payload.aud : typeof payload.aud === "string" ? [payload.aud] : [];
+  const normalizedResourceUrl = resourceUrl.replace(/\/+$/, "").toLowerCase();
+  const hasResourceAud = tokenAud.some((aud) => {
+    try {
+      return new URL(String(aud)).href.replace(/\/+$/, "").toLowerCase() === normalizedResourceUrl;
+    } catch {
+      return String(aud).toLowerCase() === normalizedResourceUrl;
+    }
+  });
+  if (!hasResourceAud) {
+    throw new Error(
+      `Access token audience [${tokenAud.join(", ")}] does not match MCP resource URL "${resourceUrl}".`
+    );
+  }
+  const grantedScopesStr = typeof tokenResponse.scope === "string" && tokenResponse.scope || typeof payload.scope === "string" && payload.scope || "";
+  const grantedList = grantedScopesStr.split(/\s+/).filter(Boolean);
+  const requestedList = scopes.split(/\s+/).filter(Boolean);
+  const matchedScopes = requestedList.filter((s) => grantedList.includes(s));
+  const matchedCapabilities = matchedScopes.filter((s) => s !== import_permissions.OFFLINE_ACCESS_SCOPE);
+  if (matchedCapabilities.length === 0) {
+    throw new Error(
+      `Access token lacks granted capability scopes (requested: [${requestedList.join(", ")}], granted: [${grantedList.join(", ")}]). At least one permission scope besides offline_access must be granted.`
+    );
+  }
+  const organizationId = typeof payload.organizationId === "string" ? payload.organizationId : null;
+  const expiresAtMs = tokenResponse.expires_in ? Date.now() + tokenResponse.expires_in * 1e3 : typeof payload.exp === "number" ? payload.exp * 1e3 : Date.now() + 36e5;
+  const credentials = {
+    serverUrl,
+    clientId,
+    accessToken: tokenResponse.access_token,
+    refreshToken: tokenResponse.refresh_token,
+    tokenType: tokenResponse.token_type || "Bearer",
+    scope: tokenResponse.scope || scopes,
+    resource: resourceUrl,
+    organizationId,
+    expiresAt: expiresAtMs,
+    updatedAt: Date.now()
+  };
+  const profileKey = normalizeProfileKey(serverUrl, clientId);
+  await vault.save(profileKey, credentials);
+  const result = {
+    profileKey,
+    serverUrl,
+    clientId,
+    organizationId,
+    scope: credentials.scope,
+    resource: credentials.resource,
+    expiresAt: expiresAtMs
+  };
+  if (options?.json) {
+    const successEvent = {
+      event: "login_success",
+      success: true,
+      ...result
+    };
+    log(JSON.stringify(successEvent));
+  } else {
+    log("\n\u2705 Login successful!");
+    log(`- Profile:       ${profileKey}`);
+    log(`- Server:        ${serverUrl}`);
+    log(`- Client ID:     ${clientId}`);
+    log(`- Organization:  ${organizationId || "(none / platform scope)"}`);
+    log(`- Scopes:        ${credentials.scope || "none"}`);
+    log(`- Resource:      ${resourceUrl}`);
+    log(`- Expires:       ${new Date(expiresAtMs).toISOString()}
+`);
+  }
+  return result;
+}
+async function executeStatus(options) {
+  const log = options?.logger || ((msg) => process.stdout.write(`${msg}
+`));
+  const serverUrl = resolveAuthServerUrl(options?.server);
+  const clientId = (options?.clientId || DEFAULT_CLI_CLIENT_ID).trim();
+  const profileKey = normalizeProfileKey(serverUrl, clientId);
+  const vault = options?.vault || new CredentialVault();
+  const creds = await vault.load(profileKey);
+  if (!creds) {
+    if (options?.json) {
+      log(JSON.stringify({ authenticated: false, profileKey, serverUrl, clientId }));
+    } else {
+      log(`No active session found for profile: ${profileKey}`);
+      log(`Run \`iwas login --server ${serverUrl}\` to authenticate.
+`);
+    }
+    return;
+  }
+  const isExpired = isCredentialExpired(creds, 60);
+  const statusData = {
+    authenticated: !isExpired,
+    expired: isExpired,
+    profileKey,
+    serverUrl: creds.serverUrl,
+    clientId: creds.clientId,
+    organizationId: creds.organizationId,
+    scope: creds.scope,
+    resource: creds.resource,
+    expiresAt: new Date(creds.expiresAt).toISOString(),
+    expiresInSeconds: Math.max(0, Math.round((creds.expiresAt - Date.now()) / 1e3))
+  };
+  if (options?.json) {
+    log(JSON.stringify(statusData));
+  } else {
+    log("\n============================================================");
+    log("                   IWAS MCP Auth Status                     ");
+    log("============================================================\n");
+    log(`- Profile:       ${profileKey}`);
+    log(`- Server:        ${creds.serverUrl}`);
+    log(`- Client ID:     ${creds.clientId}`);
+    log(`- Status:        ${isExpired ? "\u{1F534} Expired" : "\u{1F7E2} Active"}`);
+    log(`- Organization:  ${creds.organizationId || "(none / platform scope)"}`);
+    log(`- Scopes:        ${creds.scope || "none"}`);
+    if (creds.resource) {
+      log(`- Resource:      ${creds.resource}`);
+    }
+    log(`- Expires:       ${statusData.expiresAt} (${statusData.expiresInSeconds}s remaining)
+`);
+  }
+}
+
+// src/bin.ts
+var CLI_NAME = "iwas";
+var CLI_VERSION = "1.0.0";
+function printHelp(write = (msg) => process.stdout.write(msg)) {
+  const helpText = `
+${CLI_NAME} \u2014 Intelligent WiFi Access & Presence Service (IWAS) MCP CLI
+
+USAGE:
+  ${CLI_NAME} <command> [options]
+  iwas-mcp <command> [options]
+
+COMMANDS:
+  login     Authenticate using OAuth 2.0 Device Authorization Grant (RFC 8628)
+  status    Display current authentication status for a server profile
+  logout    Remove stored credentials for a server profile
+  help      Display help information
+
+OPTIONS:
+  -s, --server <url>       Auth server origin (default: $IWAS_SERVER_URL or https://getiwas.com)
+  -r, --resource <url>     MCP resource endpoint (default: \${server}/mcp)
+  -c, --client-id <id>     OAuth client ID (default: iwas-cli)
+      --scopes <scopes>    OAuth scopes (default: read-only scopes + offline_access)
+      --no-browser         Do not open the verification URL in browser
+      --json               Output result in machine-readable JSON format
+  -f, --force              Force local logout if server is unreachable
+  -h, --help               Display help
+  -v, --version            Display CLI version
+
+EXAMPLES:
+  ${CLI_NAME} login
+  ${CLI_NAME} login --server https://getiwas.com --no-browser
+  ${CLI_NAME} status
+  ${CLI_NAME} logout
+  ${CLI_NAME} logout --force
+`;
+  write(helpText.trimStart() + "\n");
+}
+async function runCli(argv = process.argv.slice(2), io) {
+  const writeOut = io?.stdout || ((msg) => process.stdout.write(msg));
+  const writeErr = io?.stderr || ((msg) => process.stderr.write(msg));
+  const exitFn = io?.exit || ((code) => process.exit(code));
+  let parsed;
+  try {
+    parsed = (0, import_node_util.parseArgs)({
+      args: argv,
+      options: {
+        server: { type: "string", short: "s" },
+        resource: { type: "string", short: "r" },
+        "client-id": { type: "string", short: "c" },
+        scopes: { type: "string" },
+        "no-browser": { type: "boolean", default: false },
+        json: { type: "boolean", default: false },
+        force: { type: "boolean", short: "f", default: false },
+        help: { type: "boolean", short: "h", default: false },
+        version: { type: "boolean", short: "v", default: false }
+      },
+      allowPositionals: true,
+      strict: true
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    writeErr(`Error: ${msg}
+`);
+    writeErr(`Run \`${CLI_NAME} --help\` for usage.
+`);
+    exitFn(1);
+    return;
+  }
+  const { values, positionals } = parsed;
+  if (values.version) {
+    writeOut(`${CLI_NAME} v${CLI_VERSION}
+`);
+    return;
+  }
+  const command = positionals[0] || "";
+  if (values.help || !command || command === "help") {
+    printHelp(writeOut);
+    return;
+  }
+  const server = typeof values.server === "string" ? values.server : void 0;
+  const resource = typeof values.resource === "string" ? values.resource : void 0;
+  const clientId = typeof values["client-id"] === "string" ? values["client-id"] : void 0;
+  const scopes = typeof values.scopes === "string" ? values.scopes : void 0;
+  const noBrowser = values["no-browser"] === true;
+  const json = values.json === true;
+  const vault = io?.vault;
+  try {
+    switch (command) {
+      case "login": {
+        await executeLogin({
+          server,
+          resource,
+          clientId,
+          scopes,
+          noBrowser,
+          json,
+          vault,
+          logger: (msg) => writeOut(`${msg}
+`),
+          errorLogger: (msg) => writeErr(`${msg}
+`)
+        });
+        break;
+      }
+      case "status": {
+        await executeStatus({
+          server,
+          clientId,
+          json,
+          vault,
+          logger: (msg) => writeOut(`${msg}
+`)
+        });
+        break;
+      }
+      case "logout": {
+        const force = values.force === true;
+        await executeLogout({
+          server,
+          clientId,
+          force,
+          json,
+          vault,
+          logger: (msg) => writeOut(`${msg}
+`),
+          errorLogger: (msg) => writeErr(`${msg}
+`)
+        });
+        break;
+      }
+      default: {
+        writeErr(`Unknown command: "${command}"
+`);
+        writeErr(`Run \`${CLI_NAME} --help\` for list of available commands.
+`);
+        exitFn(1);
+        return;
+      }
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (values.json) {
+      writeOut(JSON.stringify({ event: "error", error: message }) + "\n");
+    } else {
+      writeErr(`
+\u274C Error: ${message}
+
+`);
+    }
+    exitFn(1);
+  }
+}
+if (require.main === module) {
+  runCli();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CLI_NAME,
+  CLI_VERSION,
+  printHelp,
+  runCli
+});