@deque/axe-auth 1.1.0-next.cc7aaec1 → 1.1.0-next.cd6c9e1a

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/cli/commonArgs.d.ts

@@ -1,37 +1,18 @@
 import type { ParseArgsConfig } from "node:util";
-/**
- * Default axe server URL for `axe-auth` users on Deque's SaaS prod
- * deployment. The CLI's `--server` flag (and `AXE_SERVER_URL` env)
- * override this; non-prod customers must supply their own walnut URL.
- */
+/** Default axe server URL for Deque SaaS prod. */
 export declare const DEFAULT_WALNUT_URL = "https://axe.deque.com";
 /** Common configuration the CLI verbs share. */
 export interface CommonArgs {
-    /**
-     * axe server URL (walnut). Used by `login` to fetch
-     * `/api/sso-config` and derive the OAuth issuer / realm / client
-     * coordinates. `token` and `logout` operate on the stored entry
-     * alone and ignore this value.
-     */
+    /** axe server URL (walnut). */
     walnutURL: string;
-    /**
-     * Whether to permit non-loopback http walnut/issuer URLs. Loopback
-     * hosts (`localhost` / `127.0.0.1` / `[::1]`) are always allowed
-     * over http; this flag is the opt-in for non-loopback http
-     * deployments.
-     */
+    /** Whether non-loopback http walnut/issuer URLs are permitted. */
     allowInsecureIssuer: boolean;
 }
 /**
- * `parseArgs`-shaped options describing the flags every CLI verb
- * accepts (--server, --allow-insecure-issuer, --no-allow-insecure-issuer).
- * Subcommands spread this into their own `options` so they can add
- * verb-specific flags alongside.
- *
- * Node's `parseArgs` doesn't support `--no-` boolean negation
- * natively, so the opt-out is registered as its own flag. Passing
- * both `--allow-insecure-issuer` and `--no-allow-insecure-issuer` is
- * treated as user error and rejected.
+ * `parseArgs`-shaped options shared by every CLI verb. `parseArgs`
+ * doesn't support `--no-` boolean negation natively, so the opt-out
+ * is registered as its own flag and `parseCommonArgs` rejects passing
+ * both together.
  */
 export declare const COMMON_OPTIONS: NonNullable<ParseArgsConfig["options"]>;
 /** Subset of `parseArgs(...).values` this helper consumes. */
@@ -40,43 +21,15 @@ export interface ParsedCommonValues {
     "allow-insecure-issuer"?: boolean;
     "no-allow-insecure-issuer"?: boolean;
 }
-/**
- * Subset of a stored entry used as a fallback for
- * `allowInsecureIssuer` when the user passes neither
- * `--allow-insecure-issuer` nor `--no-allow-insecure-issuer`.
- * Sourced from `KeyringTokenStore.load()` by the dispatcher.
- *
- * `walnutURL` is carried alongside so the fallback only applies when
- * the user is targeting the same deployment as the stored entry —
- * otherwise a dev-time HTTP-allow setting would silently carry over
- * to a prod login.
- */
+/** Stored fallback for `allowInsecureIssuer` + the `walnutURL` it was minted against. */
 export interface StoredCommonDefaults {
     walnutURL: string;
     allowInsecureIssuer: boolean;
 }
 /**
  * Resolves common configuration from parsed flag values, falling
- * back to `AXE_SERVER_URL` when `--server` is absent and finally to
- * the SaaS prod walnut URL when neither is set.
- *
- * `allowInsecureIssuer` is consumed by `login` (it is forwarded to
- * SSO discovery and the OAuth flow). The fallback to a stored value
- * exists so an interactive re-login on a private dev instance does
- * not need the flag re-passed when the previous login set it. The
- * fallback is gated on the resolved walnut URL matching the stored
- * one: a user logging in to a different deployment must opt back in
- * with `--allow-insecure-issuer` explicitly. The `token` and `logout`
- * verbs do **not** consume this resolved value — they read
- * `allowInsecureIssuer` directly from the keychain entry's metadata,
- * so flag/env input is silently ignored there (and the help text for
- * those verbs documents that).
- *
- * @param values   The `values` object returned from `parseArgs`.
- * @param env      Environment to consult for fallback. Defaults to
- *   `process.env`; injected for test determinism.
- * @param defaults Stored fallback for `allowInsecureIssuer` plus the
- *   `walnutURL` it was minted against. Pass `null` (or omit) when
- *   nothing is stored.
+ * back to `AXE_SERVER_URL` and finally to `DEFAULT_WALNUT_URL`.
+ * `allowInsecureIssuer` falls back to `defaults` only when the
+ * resolved walnut URL matches `defaults.walnutURL`.
  */
 export declare function parseCommonArgs(values: ParsedCommonValues, env?: NodeJS.ProcessEnv, defaults?: StoredCommonDefaults | null): CommonArgs;

package/dist/cli/commonArgs.js

@@ -6,22 +6,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.COMMON_OPTIONS = exports.DEFAULT_WALNUT_URL = void 0;
 exports.parseCommonArgs = parseCommonArgs;
 const remove_trailing_slash_1 = __importDefault(require("remove-trailing-slash"));
-/**
- * Default axe server URL for `axe-auth` users on Deque's SaaS prod
- * deployment. The CLI's `--server` flag (and `AXE_SERVER_URL` env)
- * override this; non-prod customers must supply their own walnut URL.
- */
+/** Default axe server URL for Deque SaaS prod. */
 exports.DEFAULT_WALNUT_URL = "https://axe.deque.com";
 /**
- * `parseArgs`-shaped options describing the flags every CLI verb
- * accepts (--server, --allow-insecure-issuer, --no-allow-insecure-issuer).
- * Subcommands spread this into their own `options` so they can add
- * verb-specific flags alongside.
- *
- * Node's `parseArgs` doesn't support `--no-` boolean negation
- * natively, so the opt-out is registered as its own flag. Passing
- * both `--allow-insecure-issuer` and `--no-allow-insecure-issuer` is
- * treated as user error and rejected.
+ * `parseArgs`-shaped options shared by every CLI verb. `parseArgs`
+ * doesn't support `--no-` boolean negation natively, so the opt-out
+ * is registered as its own flag and `parseCommonArgs` rejects passing
+ * both together.
  */
 exports.COMMON_OPTIONS = {
     server: { type: "string" },
@@ -30,27 +21,9 @@ exports.COMMON_OPTIONS = {
 };
 /**
  * Resolves common configuration from parsed flag values, falling
- * back to `AXE_SERVER_URL` when `--server` is absent and finally to
- * the SaaS prod walnut URL when neither is set.
- *
- * `allowInsecureIssuer` is consumed by `login` (it is forwarded to
- * SSO discovery and the OAuth flow). The fallback to a stored value
- * exists so an interactive re-login on a private dev instance does
- * not need the flag re-passed when the previous login set it. The
- * fallback is gated on the resolved walnut URL matching the stored
- * one: a user logging in to a different deployment must opt back in
- * with `--allow-insecure-issuer` explicitly. The `token` and `logout`
- * verbs do **not** consume this resolved value — they read
- * `allowInsecureIssuer` directly from the keychain entry's metadata,
- * so flag/env input is silently ignored there (and the help text for
- * those verbs documents that).
- *
- * @param values   The `values` object returned from `parseArgs`.
- * @param env      Environment to consult for fallback. Defaults to
- *   `process.env`; injected for test determinism.
- * @param defaults Stored fallback for `allowInsecureIssuer` plus the
- *   `walnutURL` it was minted against. Pass `null` (or omit) when
- *   nothing is stored.
+ * back to `AXE_SERVER_URL` and finally to `DEFAULT_WALNUT_URL`.
+ * `allowInsecureIssuer` falls back to `defaults` only when the
+ * resolved walnut URL matches `defaults.walnutURL`.
  */
 function parseCommonArgs(values, env = process.env, defaults = null) {
     const walnutURL = (0, remove_trailing_slash_1.default)(values.server ?? env.AXE_SERVER_URL ?? exports.DEFAULT_WALNUT_URL);

package/dist/cli/confirm.js

@@ -9,9 +9,6 @@ const node_readline_1 = require("node:readline");
  * default action stays conservative.
  */
 async function confirm(options) {
-    // Annotate after the ?? fallbacks so the union of `Writable |
-    // NodeJS.WriteStream` (from `process.stderr`) collapses to the
-    // base class — otherwise `output.write(...)` is ambiguous.
     const input = options.input ?? process.stdin;
     const output = options.output ?? process.stderr;
     const question = options.question.endsWith(" ")

package/dist/cli/errors.d.ts

@@ -2,19 +2,12 @@
 export type CLIErrorCode = "NOT_AUTHENTICATED" | "USER_CANCELLED" | "ALREADY_AUTHENTICATED" | "OAUTH_FAILED" | "KEYCHAIN_FAILURE";
 /**
  * Thrown from a verb's `run` to signal a known failure. The
- * dispatcher in `src/index.ts` writes `message` to stderr and exits
- * with `exitCode`. The `code` field is the load-bearing
- * discriminator; `exitCode` is derived for shell scripts and is
- * documented in the README.
+ * dispatcher writes `message` to stderr and exits with `exitCode`.
  */
 export declare class CLIError extends Error {
     readonly code: CLIErrorCode;
     readonly exitCode: number;
     constructor(code: CLIErrorCode, message: string);
 }
-/**
- * Returns the `message` of an `Error`-shaped value, or its `String`
- * coercion otherwise. Used in user-facing error templates so
- * callers don't inline the `instanceof` ternary every time.
- */
+/** Returns the `message` of an `Error`, or its `String` coercion otherwise. */
 export declare function describeError(err: unknown): string;

package/dist/cli/errors.js

@@ -11,10 +11,7 @@ const EXIT_CODE_BY_ERROR_CODE = {
 };
 /**
  * Thrown from a verb's `run` to signal a known failure. The
- * dispatcher in `src/index.ts` writes `message` to stderr and exits
- * with `exitCode`. The `code` field is the load-bearing
- * discriminator; `exitCode` is derived for shell scripts and is
- * documented in the README.
+ * dispatcher writes `message` to stderr and exits with `exitCode`.
  */
 class CLIError extends Error {
     code;
@@ -27,11 +24,7 @@ class CLIError extends Error {
     }
 }
 exports.CLIError = CLIError;
-/**
- * Returns the `message` of an `Error`-shaped value, or its `String`
- * coercion otherwise. Used in user-facing error templates so
- * callers don't inline the `instanceof` ternary every time.
- */
+/** Returns the `message` of an `Error`, or its `String` coercion otherwise. */
 function describeError(err) {
     return err instanceof Error ? err.message : String(err);
 }

package/dist/cli/types.d.ts

@@ -4,48 +4,22 @@ import type { LoadResult } from "../oauth/tokenStore";
 import type { CommonArgs } from "./commonArgs";
 /** Mapping passed to `parseArgs` for verb-specific flags. */
 export type VerbOptions = NonNullable<ParseArgsConfig["options"]>;
-/**
- * The injectables every CLI verb sees. The dispatcher fills these in
- * with the real `process.*` streams; tests pass synthetic values.
- * Verb-specific overrides (e.g. `getToken`, `authorize`) extend this
- * interface in the relevant verb's module — TS allows the dispatcher
- * to pass a plain `CommandDeps` because the verb-specific extras are
- * declared optional.
- */
+/** Injectables every CLI verb sees. Dispatcher fills with `process.*`; tests pass synthetic values. */
 export interface CommandDeps {
-    /**
-     * Standard input. Carries an optional `isTTY` so verbs like
-     * `login` can branch on interactivity. Real `process.stdin`
-     * satisfies the shape; test fixtures using `Readable.from([])`
-     * leave `isTTY` undefined, which coerces to `false`.
-     */
+    /** `isTTY` is optional so `Readable.from([])` test fixtures coerce to non-TTY. */
     stdin: Readable & {
         isTTY?: boolean;
     };
     stdout: Writable;
     stderr: Writable;
     /**
-     * Pre-loaded result of `KeyringTokenStore.load()`, populated by the
-     * dispatcher when it ran the keychain read to derive the
-     * `parseCommonArgs` fallback. Verbs prefer this over loading
-     * again so a single `axe-auth token` invocation hits the keychain
-     * once instead of three times. Tests typically leave this
-     * undefined and inject a fake `tokenStore` instead.
+     * Pre-loaded result of `KeyringTokenStore.load()` from the
+     * dispatcher's keychain read, so a single CLI invocation hits the
+     * keychain once instead of N times.
      */
     loadedEntry?: LoadResult;
 }
-/**
- * Specification of a single CLI verb. The dispatcher in
- * `src/index.ts` consumes one of these per registered command:
- * parses argv, resolves common args, prints `helpText` for `--help`,
- * runs `run`, and translates thrown `CLIError`s (see `./errors`)
- * into exit codes.
- *
- * Each verb narrows the `run` parameters to its own
- * `CommonArgs & <Verb>Flags` and `<Verb>Deps`. Method-shorthand
- * bivariance lets that narrower signature satisfy this interface
- * without casts at the verb definition.
- */
+/** Specification of a single CLI verb consumed by the dispatcher. */
 export interface CommandSpec {
     /** Verb name, e.g. `"login"`. */
     readonly name: string;
@@ -53,27 +27,13 @@ export interface CommandSpec {
     readonly summary: string;
     /** Full help text printed for `axe-auth <verb> --help`. */
     readonly helpText: string;
-    /**
-     * Verb-specific `parseArgs` options. Common options
-     * (`--server` / `--allow-insecure-issuer` / `--no-allow-insecure-issuer`)
-     * are added by the dispatcher; do not duplicate them here.
-     */
+    /** Verb-specific `parseArgs` options; common options are added by the dispatcher. */
     readonly options: VerbOptions;
-    /**
-     * `true` if this verb cannot run without a usable walnut URL
-     * (login). `false` for verbs that operate on the stored entry
-     * alone (token, logout) and have their own "not authenticated" /
-     * "already logged out" handling for the empty-entry case. With
-     * the SaaS prod default in `parseCommonArgs`, the walnut URL is
-     * never strictly missing, but this flag remains for future
-     * required-config additions.
-     */
+    /** `true` if this verb cannot run without a usable walnut URL (login). */
     readonly requiresConfig: boolean;
     /**
-     * Run the verb with already-resolved args and the dispatcher's
-     * deps. Throw a `CLIError` to signal a known failure with an
-     * explicit exit code; throw any other error for a generic exit
-     * code 2 plus the error message on stderr.
+     * Throw `CLIError` for a known failure with an explicit exit code;
+     * any other error becomes exit code 2 with the message on stderr.
      */
     run(args: CommonArgs, deps: CommandDeps): Promise<void>;
 }

package/dist/commands/login.d.ts

@@ -17,10 +17,7 @@ export interface LoginDeps extends CommandDeps {
      * so the pre-check and post-flow save agree on the keychain entry.
      */
     tokenStore?: TokenStore;
-    /**
-     * Override the confirmation prompt (for tests). Receives the
-     * issuer URL and returns whether the user wants to proceed.
-     */
+    /** Override the confirmation prompt (for tests). */
     confirm?: (prompt: string) => Promise<boolean>;
 }
 /** Verb-specific flags for `axe-auth login`. */

package/dist/commands/login.js

@@ -32,9 +32,6 @@ const loginCommand = {
                 output: deps.stderr,
             }));
         const tokenStore = deps.tokenStore ?? new tokenStore_1.KeyringTokenStore();
-        // 1. Ask the axe server where its Keycloak lives and which client to use.
-        //    This is the only step that hits the axe server directly; from here on
-        //    the CLI talks to Keycloak using the discovered coordinates.
         let ssoConfig;
         try {
             ssoConfig = await discoverFn(args.walnutURL, {
@@ -49,16 +46,11 @@ const loginCommand = {
         }
         const issuerURL = `${(0, remove_trailing_slash_1.default)(ssoConfig.url)}/auth/realms/${ssoConfig.realm}`;
         const clientId = ssoConfig.mcpClientId;
-        // 2. Re-auth confirmation. Same UX as the previous flag-driven
-        //    flow, but the comparison is against the *discovered* issuer
-        //    + client, not user-supplied flags.
         if (!args.force) {
             const stored = deps.loadedEntry ?? (await tokenStore.load());
             if (!stored.ok && stored.reason !== "empty") {
-                // Existing entry is unreadable (corrupt or stored under a
-                // schema we can't migrate). authorize() will overwrite it
-                // either way, but the user deserves a breadcrumb for what
-                // disappeared.
+                // authorize() will overwrite either way, but the user
+                // deserves a breadcrumb for what disappeared.
                 deps.stderr.write(`axe-auth: replacing unreadable stored credentials (${stored.reason}).\n`);
             }
             if (stored.ok) {
@@ -86,9 +78,8 @@ const loginCommand = {
                 }
             }
         }
-        // 3. Drive the OAuth flow. The originating axe server URL rides along
-        //    so it lands in the StoredEntry and future verbs (re-discovery,
-        //    revoke) can operate without user-supplied flags.
+        // `walnutURL` lands in the StoredEntry so future verbs
+        // (re-discovery, revoke) operate without user-supplied flags.
         try {
             await authorizeFn({
                 issuerURL,

package/dist/commands/logout.js

@@ -16,8 +16,6 @@ const logoutCommand = {
         const discoverFn = deps.discoverOIDC ?? discoverOIDC_1.discoverOIDC;
         const revokeFn = deps.revokeRefreshToken ?? revokeToken_1.revokeRefreshToken;
         const tokenStore = deps.tokenStore ?? new tokenStore_1.KeyringTokenStore();
-        // Prefer the entry the dispatcher already loaded; only fall back
-        // to a fresh read when there isn't one (test path).
         const loaded = deps.loadedEntry ?? (await tokenStore.load());
         if (!loaded.ok) {
             if (loaded.reason === "empty") {

package/dist/commands/token.js

@@ -15,10 +15,6 @@ const tokenCommand = {
     async run(_args, deps) {
         const getToken = deps.getToken ?? getValidAccessToken_1.getValidAccessToken;
         const tokenStore = deps.tokenStore ?? new tokenStore_1.KeyringTokenStore();
-        // Stored entry is the only source of truth: single-entry-per-machine
-        // model, the blob carries the issuer/client coordinates the tokens
-        // were minted against, and there is no longer a flag to override
-        // them with.
         const loaded = deps.loadedEntry ?? (await tokenStore.load());
         let token;
         try {

package/dist/index.js

@@ -14,7 +14,6 @@ const logout_1 = __importDefault(require("./commands/logout"));
 const token_1 = __importDefault(require("./commands/token"));
 const errors_1 = require("./cli/errors");
 const pkg = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, "..", "package.json"), "utf-8"));
-// Iteration order is the order verbs appear in `axe-auth --help`.
 const COMMANDS = [
     login_1.default,
     logout_1.default,
@@ -82,14 +81,9 @@ async function dispatch(argv) {
         process.stdout.write(`${command.helpText}\n`);
         return 0;
     }
-    // Best-effort load of the stored entry. Used to (a) supply the
-    // `allowInsecureIssuer` fallback on flag-free invocations, and (b)
-    // hand the entry to the verb via `deps.loadedEntry` so a single
-    // `axe-auth token` invocation hits the keychain once instead of
-    // twice. A read failure here is non-fatal — `parseCommonArgs`
-    // always succeeds (the SaaS prod default fills any unsupplied
-    // walnut URL), and verbs that need a stored entry have their own
-    // empty/corrupt-entry handling.
+    // Best-effort load: handed to verbs via `deps.loadedEntry` so a
+    // single CLI invocation hits the keychain once. Read failure is
+    // non-fatal — verbs handle their own empty/corrupt cases.
     let defaults = null;
     let loadedEntry;
     try {
@@ -102,9 +96,8 @@ async function dispatch(argv) {
         }
     }
     catch {
-        // Keychain unavailable: leave defaults null. login will fail at
-        // `tokenStore.save()` with a clearer error than we can produce
-        // here; token / logout's own empty-entry path handles it.
+        // Keychain unavailable: leave defaults null. Verbs surface their
+        // own clearer errors at the actual save / read site.
     }
     let common;
     try {

package/dist/oauth/authorizationURL.d.ts

@@ -10,12 +10,7 @@ export interface BuildAuthorizationURLOptions {
     codeChallenge: string;
     /** CSRF `state` value, echoed by the auth server and validated on callback. */
     state: string;
-    /**
-     * OAuth scopes to request. No default — callers must choose explicitly.
-     * Keycloak-idiomatic value for a refresh-token flow is `["offline_access"]`;
-     * Google uses `access_type=offline` (a custom parameter) instead; Auth0
-     * tolerates `offline_access` only with specific audience settings.
-     */
+    /** OAuth scopes to request. No default; callers choose explicitly. */
     scopes: readonly string[];
 }
 /**

package/dist/oauth/authorizationURL.js

@@ -2,12 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildAuthorizationURL = buildAuthorizationURL;
 const errors_1 = require("./errors");
-// Names of OAuth params we always set. If any of these are already
-// present on the authorization endpoint URL returned by discovery,
-// something is wrong on the server side (or with the caller's
-// endpoint override) and silently keeping both values would be a
-// security trap: the authorization server's disambiguation is
-// unspecified and varies by implementation.
+// Pre-existing values for these on the authorization endpoint are a
+// security trap: the auth server's disambiguation is unspecified.
 const OAUTH_REQUIRED_PARAMS = [
     "response_type",
     "client_id",

package/dist/oauth/authorize.d.ts

@@ -2,72 +2,34 @@ import type { TokenSet } from "./tokenResponse";
 import { type TokenStore } from "./tokenStore";
 /** Options for `authorize`. */
 export interface AuthorizeOptions {
-    /**
-     * Authorization-server URL the discovery document claims as its
-     * `issuer`. For Keycloak, callers build this as
-     * `${serverURL}/realms/${realm}`. For other providers it is the
-     * hostname (or issuer path) advertised in their discovery document.
-     */
+    /** Issuer URL the OIDC discovery document advertises (e.g. `${serverURL}/realms/${realm}` for Keycloak). */
     issuerURL: string;
     /** OAuth client ID registered with the authorization server. */
     clientId: string;
-    /**
-     * Originating walnut (axe server) URL the user supplied (or the
-     * SaaS prod default) at login. Persisted in the stored entry
-     * alongside the OAuth coordinates so future verbs can re-discover
-     * `/api/sso-config` without user-supplied flags.
-     */
+    /** Persisted alongside the tokens so future verbs can re-discover `/api/sso-config` without flags. */
     walnutURL: string;
-    /**
-     * OAuth scopes to request. Required — this library has no opinion
-     * about which scopes your provider expects. Keycloak callers who
-     * want a refresh token typically pass `["offline_access"]`; Google
-     * uses `access_type=offline` as a separate query param and
-     * therefore needs an empty scope list plus that param threaded
-     * through elsewhere.
-     */
+    /** OAuth scopes to request. Keycloak callers typically pass `["offline_access"]` for a refresh token. */
     scopes: readonly string[];
     /** Max time to wait for the loopback callback, in milliseconds. */
     timeoutMs?: number;
     /** Aborts the in-flight discovery, callback wait, and token exchange. */
     signal?: AbortSignal;
-    /**
-     * Override for the token persistence layer. Defaults to a fresh
-     * `KeyringTokenStore()` (single keychain entry per machine; the
-     * blob carries its own issuer/client coordinates).
-     */
+    /** Override for the token persistence layer. */
     tokenStore?: TokenStore;
     /** Override for the system browser launcher. Injected for tests. */
     openBrowser?: (url: string) => void;
-    /**
-     * Called with the authorization URL just before the browser launch.
-     * The default prints to stderr only when stderr is a TTY, so a
-     * parent CLI consuming this library as a dependency does not
-     * double-print. Pass a custom handler to route the URL through your
-     * own UI, or `() => {}` to suppress entirely.
-     */
+    /** Called with the authorization URL just before the browser launch. Default prints to stderr only when stderr is a TTY. */
     onAuthorizationUrl?: (url: string) => void;
     /**
-     * Called for soft warnings that are not errors but warrant user
-     * attention (e.g. `offline_access` was requested but the server did
-     * not return a `refresh_token`, or the browser failed to launch).
-     * The default prints to stderr only when stderr is a TTY. Pass a
-     * custom handler to route warnings through your own UI, or `() =>
-     * {}` to suppress entirely.
-     *
-     * Non-TTY callers who want warning visibility (log files, parent
-     * CLIs, background workers) should pass an explicit handler.
-     * Dropped warnings have no visible symptom at the time they fire —
-     * users only discover the consequence later (e.g. being prompted to
-     * re-authenticate at the next session).
+     * Called for soft warnings (e.g. requested `offline_access` but the
+     * server returned no refresh token, or the browser failed to
+     * launch). Default prints to stderr only when stderr is a TTY.
+     * Non-TTY callers who want warning visibility should pass an
+     * explicit handler — dropped warnings have no symptom at the time
+     * they fire; users discover the consequence later.
      */
     onWarning?: (message: string) => void;
-    /**
-     * Forwarded to the discovery step. Loopback hosts (`localhost` /
-     * `127.0.0.1` / `[::1]`) are always permitted over http; this flag
-     * is the opt-in for non-loopback http issuers and for non-loopback
-     * http endpoints returned by discovery. Default `false`.
-     */
+    /** Forwarded to discovery; permits non-loopback http issuers + endpoints. */
     allowInsecureIssuer?: boolean;
 }
 /**

package/dist/oauth/authorize.js

@@ -39,10 +39,8 @@ function defaultOnWarning(message) {
  */
 async function authorize(options) {
     const { issuerURL, clientId, walnutURL, scopes, timeoutMs, signal, tokenStore = new tokenStore_1.KeyringTokenStore(), openBrowser = openBrowser_1.openBrowser, onAuthorizationUrl = defaultOnAuthorizationUrl, onWarning = defaultOnWarning, allowInsecureIssuer, } = options;
-    // Discovery first. If the auth server is unreachable we want to fail
-    // *before* opening a browser — a rejected discovery throw is
-    // strictly more useful than a browser tab pointing at a
-    // wrong/unreachable URL.
+    // Discovery before browser-launch so a bad URL surfaces as a
+    // throw rather than a wrong/unreachable browser tab.
     const config = await (0, discoverOIDC_1.discoverOIDC)(issuerURL, {
         signal,
         allowInsecureIssuer,

package/dist/oauth/discoverOIDC.d.ts

@@ -15,36 +15,19 @@ export interface OIDCConfiguration {
 export interface DiscoverOIDCOptions {
     /** Aborts the underlying fetch when fired. */
     signal?: AbortSignal;
-    /**
-     * Permit non-HTTPS issuer URLs whose host is not a loopback literal.
-     * Loopback hosts (`localhost`, `127.0.0.1`, `[::1]`) are always
-     * allowed over http since they cannot be intercepted remotely; this
-     * flag is for corporate dev setups or reverse-proxy scenarios where
-     * http is the only available path. Default `false`.
-     */
+    /** Permit non-HTTPS issuer URLs whose host is not a loopback literal. Default `false`. */
     allowInsecureIssuer?: boolean;
 }
 /**
- * Fetches and parses the OpenID Connect discovery document for a given
- * issuer. Fails fast (no retry) so the caller does not open a browser
- * against an unreachable authorization server.
+ * Fetches and parses the OIDC discovery document. Fails fast (no
+ * retry) so the caller does not open a browser against an unreachable
+ * authorization server. Verifies the server's claimed `issuer` matches
+ * the input URL per OIDC Discovery §3 — without this, a hostile
+ * discovery response could redirect the authorization and token
+ * endpoints to attacker hosts.
  *
- * This function uses the OIDC discovery well-known path as a
- * convention — most OAuth 2.0 providers expose it regardless of
- * whether you intend to perform identity validation. This library
- * itself does not perform OIDC identity validation (no id_token /
- * nonce / signature checks); callers needing OIDC-strength identity
- * assurance should layer that on top.
- *
- * Verifies that the server's claimed `issuer` matches the URL the
- * caller passed in, per OIDC Discovery §3 / defence against a hostile
- * discovery response redirecting `authorization_endpoint` and
- * `token_endpoint` to attacker-controlled hosts.
- *
- * @param issuerURL Authorization-server URL the discovery document
- *   claims as its `issuer`. For Keycloak, callers build this as
- *   `${serverURL}/realms/${realm}`. For other providers it is the
- *   hostname (or issuer path) advertised in their discovery document.
- *   Trailing slashes tolerated.
+ * Uses the OIDC well-known path as a convention; does not perform
+ * OIDC-strength identity validation (no id_token / nonce / signature
+ * checks). Callers needing identity assurance should layer that on top.
  */
 export declare function discoverOIDC(issuerURL: string, options?: DiscoverOIDCOptions): Promise<OIDCConfiguration>;