@deque/axe-auth 1.1.0-next.dc545028 → 1.1.0-next.e9efc11b

package/credits.json

@@ -27,6 +27,17 @@
     "publisher": "Stephen Mathieson",
     "email": "me@stephenmathieson.com"
   },
+  "shlex@3.0.0": {
+    "name": "shlex",
+    "version": "3.0.0",
+    "licenses": "MIT",
+    "path": "/home/runner/work/axe-mcp-server/axe-mcp-server/node_modules/.pnpm/shlex@3.0.0/node_modules/shlex",
+    "licenseText": "MIT License\n\nCopyright (c) 2018 Ryan Govostes\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n",
+    "licenseFile": "/home/runner/work/axe-mcp-server/axe-mcp-server/node_modules/.pnpm/shlex@3.0.0/node_modules/shlex/LICENSE",
+    "repository": "https://github.com/rgov/node-shlex",
+    "publisher": "Ryan Govostes",
+    "copyright": "Copyright (c) 2018 Ryan Govostes"
+  },
   "ts-dedent@2.2.0": {
     "name": "ts-dedent",
     "version": "2.2.0",

package/dist/oauth/openBrowser.d.ts

@@ -7,13 +7,24 @@ export interface OpenBrowserOptions {
     platform?: NodeJS.Platform;
     /** Override for `child_process.spawn`. Used by tests. */
     spawnFn?: SpawnFn;
+    /**
+     * Override for `process.env.BROWSER`. The de-facto convention shared
+     * with `xdg-open` and Python's `webbrowser`: when set, it names the
+     * command to invoke instead of the platform default. Parsed shlex-style
+     * (POSIX shell tokenization) so values like `firefox --new-window` or
+     * `/path/with\ spaces/firefox` work as expected. An empty or missing
+     * value falls back to the platform default.
+     */
+    browserEnv?: string;
 }
 /**
  * Launches the system browser at `url` in a detached child process.
- * Returns synchronously once the child is spawned — completion of the
- * browser load is intentionally not awaited.
+ * Honors `$BROWSER` when set, falling back to the platform default
+ * (`open` / `xdg-open` / `cmd start`). Returns synchronously once the
+ * child is spawned — completion of the browser load is intentionally
+ * not awaited.
  *
  * @param url Absolute URL to open.
- * @param options Platform/spawn overrides; only exposed for tests.
+ * @param options Platform/spawn/env overrides; only exposed for tests.
  */
 export declare function openBrowser(url: string, options?: OpenBrowserOptions): void;

package/dist/oauth/openBrowser.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.openBrowser = openBrowser;
 const node_child_process_1 = require("node:child_process");
+const shlex_1 = require("shlex");
 const errors_1 = require("./errors");
 // On Windows `start` is a cmd.exe builtin, not a standalone binary.
 // The empty `""` pair is a positional placeholder for the window
@@ -26,7 +27,11 @@ function windowsCommand(url) {
         args: ["/c", "start", '""', url.replace(/[&|^<>"%\r\n]/g, (c) => `^${c}`)],
     };
 }
-function browserCommand(platform, url) {
+function browserCommand(platform, url, browserOverride) {
+    if (browserOverride && browserOverride.length > 0) {
+        const [command, ...extraArgs] = browserOverride;
+        return { command, args: [...extraArgs, url] };
+    }
     switch (platform) {
         case "darwin":
             return { command: "open", args: [url] };
@@ -47,16 +52,28 @@ function browserCommand(platform, url) {
 }
 /**
  * Launches the system browser at `url` in a detached child process.
- * Returns synchronously once the child is spawned — completion of the
- * browser load is intentionally not awaited.
+ * Honors `$BROWSER` when set, falling back to the platform default
+ * (`open` / `xdg-open` / `cmd start`). Returns synchronously once the
+ * child is spawned — completion of the browser load is intentionally
+ * not awaited.
  *
  * @param url Absolute URL to open.
- * @param options Platform/spawn overrides; only exposed for tests.
+ * @param options Platform/spawn/env overrides; only exposed for tests.
  */
 function openBrowser(url, options = {}) {
     const platform = options.platform ?? process.platform;
     const spawnFn = options.spawnFn ?? node_child_process_1.spawn;
-    const { command, args } = browserCommand(platform, url);
+    const browserEnv = options.browserEnv ?? process.env.BROWSER;
+    let browserOverride;
+    if (browserEnv && browserEnv.length > 0) {
+        try {
+            browserOverride = (0, shlex_1.split)(browserEnv);
+        }
+        catch (cause) {
+            throw new errors_1.OAuthFlowError("BROWSER_LAUNCH_FAILED", `Failed to parse $BROWSER (${browserEnv}). Open this URL manually:\n${url}`, { cause });
+        }
+    }
+    const { command, args } = browserCommand(platform, url, browserOverride);
     let child;
     try {
         child = spawnFn(command, args, {

package/dist/oauth/tokenStore.d.ts

@@ -100,6 +100,14 @@ export type BlobChainResult = {
  * and `MIGRATORS` and applies the latest-shape check on top.
  */
 export declare function parseAndMigrateBlob(raw: string | null, expectedVersion?: number, migrators?: ReadonlyMap<number, (old: unknown) => unknown | null>): BlobChainResult;
+/**
+ * Returns a per-platform hint appended to keychain error messages so
+ * users see actionable guidance for their OS instead of generic or
+ * Linux-only advice. Exported (but not re-exported from the package
+ * index) so tests can exercise each branch without mocking
+ * `process.platform`.
+ */
+export declare function platformKeyringHint(platform?: NodeJS.Platform): string;
 /**
  * `TokenStore` backed by the operating system's native keychain via
  * `@napi-rs/keyring` (macOS Keychain, Windows Credential Manager, Linux

package/dist/oauth/tokenStore.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KeyringTokenStore = exports.STORED_BLOB_VERSION = void 0;
 exports.parseAndMigrateBlob = parseAndMigrateBlob;
+exports.platformKeyringHint = platformKeyringHint;
 const errors_1 = require("./errors");
 const keyringBinding_1 = require("./keyringBinding");
 // On macOS: Keychain generic password item with the service name below.
@@ -153,7 +154,27 @@ function parseAndMigrateBlob(raw, expectedVersion = exports.STORED_BLOB_VERSION,
     return { ok: true, blob: current };
 }
 function wrapKeyringError(op, cause) {
-    throw new errors_1.OAuthFlowError("KEYRING_UNAVAILABLE", `System keychain ${op} failed. On Linux this usually means no D-Bus Secret Service is running.`, { cause });
+    const causeMessage = cause instanceof Error ? cause.message : String(cause);
+    throw new errors_1.OAuthFlowError("KEYRING_UNAVAILABLE", `System keychain ${op} failed: ${causeMessage}. ${platformKeyringHint()}`, { cause });
+}
+/**
+ * Returns a per-platform hint appended to keychain error messages so
+ * users see actionable guidance for their OS instead of generic or
+ * Linux-only advice. Exported (but not re-exported from the package
+ * index) so tests can exercise each branch without mocking
+ * `process.platform`.
+ */
+function platformKeyringHint(platform = process.platform) {
+    switch (platform) {
+        case "darwin":
+            return "On macOS this usually means Keychain Access denied or cancelled the prompt.";
+        case "win32":
+            return "On Windows this usually means Credential Manager rejected the operation.";
+        case "linux":
+            return "On Linux this usually means no D-Bus Secret Service is running (e.g. GNOME Keyring or KWallet).";
+        default:
+            return `Underlying platform: ${platform}.`;
+    }
 }
 /**
  * `TokenStore` backed by the operating system's native keychain via

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deque/axe-auth",
-  "version": "1.1.0-next.dc545028",
+  "version": "1.1.0-next.e9efc11b",
   "description": "CLI authentication utility for Deque services",
   "license": "SEE LICENSE IN LICENSE",
   "type": "commonjs",
@@ -25,11 +25,14 @@
   "dependencies": {
     "@napi-rs/keyring": "^1.2.0",
     "remove-trailing-slash": "^0.1.1",
+    "shlex": "^3.0.0",
     "ts-dedent": "^2.2.0"
   },
   "devDependencies": {
+    "@hono/node-server": "^1.19.14",
     "@types/node": "^22.13.10",
     "c8": "^10.1.3",
+    "hono": "^4.12.15",
     "tsx": "^4.20.6",
     "typescript": "^5.9.3"
   },