@deque/axe-auth 1.1.0-next.487d00fa → 1.1.0-next.49c17a1d

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

@@ -41,6 +41,8 @@ export type OAuthFlowErrorCode =
  | "TOKEN_EXCHANGE_FAILED"
 /** System keychain is unavailable (e.g. no D-Bus secret service on Linux). */
  | "KEYRING_UNAVAILABLE"
+/** OAuth blob is too large for the OS keystore (Windows Credential Manager: 2560 UTF-16 chars per entry, MAX_CHUNKS chunks max). The keystore itself is healthy; the IDP is issuing tokens with too many claims. */
+ | "TOKEN_TOO_LARGE"
 /** Authorization endpoint returned by discovery cannot be used (e.g. already carries an OAuth-required param). Server misconfiguration. */
  | "INVALID_AUTHORIZATION_ENDPOINT"
 /** No usable stored credentials; the user needs to run `login` to re-authenticate. Covers empty / corrupt / version-mismatched store and refresh tokens the authorization server has revoked. */

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

@@ -1,5 +1,13 @@
 import { type KeyringEntryFactory } from "./keyringBinding";
 import type { TokenSet } from "./tokenResponse";
+/**
+ * Whether `KeyringTokenStore` should split the stored blob across
+ * multiple keychain entries on this platform. Windows-only because of
+ * Credential Manager's 2560 UTF-16 character per-entry cap. Exported
+ * (parameterized for tests) so the chunking path can be exercised
+ * deterministically.
+ */
+export declare function shouldChunkForKeyring(platform?: NodeJS.Platform): boolean;
 /**
  * Current on-disk blob schema version. Exported so consumers can
  * display "stored v:N, expected v:M" diagnostics when `load()` returns
@@ -100,17 +108,76 @@ 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;
+/**
+ * Builds the user-facing keychain error message. Platform is a
+ * parameter (defaulting to `process.platform`) so tests can drive each
+ * branch without mocking the runtime; mirrors the pattern in
+ * `platformKeyringHint`.
+ *
+ * The Windows-specific size-limit message is only used when the
+ * underlying error matches the binding's "longer than the platform
+ * limit" wording AND the runtime is win32 — that combination is the
+ * only way the size cap actually manifests in practice. On other
+ * platforms (or for any other binding error) we fall back to the
+ * generic per-platform hint.
+ */
+export declare function keyringErrorMessage(op: string, cause: unknown, platform?: NodeJS.Platform): string;
+/**
+ * Detects the `@napi-rs/keyring` error string for "value too large".
+ * In practice only Windows Credential Manager triggers this — its
+ * stored values are capped at 2560 UTF-16 chars; macOS Keychain and
+ * Linux libsecret have no comparable limit. Exported (but not
+ * re-exported from the package index) so tests can exercise the
+ * detector independently of the wrap path.
+ */
+export declare function isKeyringSizeError(cause: unknown): boolean;
+/**
+ * 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
- * Secret Service). One entry per machine, keyed by a fixed account
- * name; the blob carries its own issuer/client coordinates so verbs
- * can recover full config without per-issuer keying.
+ * Secret Service). On macOS and Linux the blob lives in a single entry
+ * keyed by the fixed `credentials` account name. On Windows the blob
+ * is split across `credentials.0`, `credentials.1`, … entries to fit
+ * under Credential Manager's 2560 UTF-16 character per-entry cap; see
+ * `shouldChunkForKeyring`.
+ *
+ * The blob carries its own issuer/client coordinates so verbs can
+ * recover full config without per-issuer keying.
  */
 export declare class KeyringTokenStore implements TokenStore {
     #private;
+    /**
+     * @param entryFactory Injection seam for `@napi-rs/keyring` entries.
+     *   Defaults to the production lazy-resolved factory; tests pass a
+     *   recording / faking variant.
+     */
     constructor(entryFactory?: KeyringEntryFactory);
+    /**
+     * @internal Test seam. Constructs a store with an explicit chunking
+     * decision instead of the platform-determined default, so the
+     * chunked path can be exercised on macOS/Linux CI and the unchunked
+     * path on Windows CI. Production code must use the regular
+     * constructor and let `shouldChunkForKeyring()` decide — passing
+     * `chunked: true` on macOS would write data that the regular
+     * constructor wouldn't be able to read.
+     */
+    static forTesting(entryFactory: KeyringEntryFactory, chunked: boolean): KeyringTokenStore;
     save(entry: StoredEntry): Promise<void>;
     load(): Promise<LoadResult>;
     clear(): Promise<void>;
 }
+/**
+ * Splits `blob` into the N parts that `KeyringTokenStore.#saveChunked`
+ * writes to `credentials.0..N-1`. Chunk 0 is prefixed with `<N>\n` so
+ * the reader can learn N from a single getPassword call. Each chunk
+ * stays under `CHUNK_LIMIT` UTF-16 characters; throws if the blob would
+ * require more than `MAX_CHUNKS` chunks. Exported for tests.
+ */
+export declare function chunkBlobForKeyring(blob: string): string[];

package/dist/oauth/tokenStore.js

@@ -1,7 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KeyringTokenStore = exports.STORED_BLOB_VERSION = void 0;
+exports.shouldChunkForKeyring = shouldChunkForKeyring;
 exports.parseAndMigrateBlob = parseAndMigrateBlob;
+exports.keyringErrorMessage = keyringErrorMessage;
+exports.isKeyringSizeError = isKeyringSizeError;
+exports.platformKeyringHint = platformKeyringHint;
+exports.chunkBlobForKeyring = chunkBlobForKeyring;
 const errors_1 = require("./errors");
 const keyringBinding_1 = require("./keyringBinding");
 // On macOS: Keychain generic password item with the service name below.
@@ -9,16 +14,45 @@ const keyringBinding_1 = require("./keyringBinding");
 // Exposed as a human-readable string because these all surface the service
 // name in OS UIs (Keychain Access, credmgr.exe, seahorse).
 const SERVICE_NAME = "axe-auth";
-// Single keychain entry per machine. The blob it holds is fully
-// self-describing (issuerURL, clientId, allowInsecureIssuer, plus the
-// tokens), so verbs that don't pass `--server` / `--realm` /
-// `--client-id` can resolve their config from the entry.
+// Single keychain entry per machine on macOS / Linux. (Windows splits
+// across `credentials.0`, `credentials.1`, … — see `CHUNK_LIMIT`
+// below.) The blob it holds is fully self-describing (issuerURL,
+// clientId, allowInsecureIssuer, plus the tokens), so verbs that
+// don't pass `--server` / `--realm` / `--client-id` can resolve their
+// config from the entry.
 //
 // Account name is human-readable so users investigating the entry in
 // macOS Keychain Access (or `secret-tool` on Linux, credmgr on
 // Windows) can tell what it is. Not versioned: the schema version
-// lives inside the blob and migrators handle the upgrade path.
+// lives inside the blob and migrators handle the upgrade path. Note:
+// Windows entries hold base64-encoded JSON rather than the raw JSON
+// macOS / Linux store, so a Windows user inspecting their Credential
+// Manager will see opaque base64; that's a side effect of chunking.
 const ACCOUNT_NAME = "credentials";
+// Windows Credential Manager caps stored values at 2560 UTF-16 code
+// units, which large OAuth access-token JWTs (many groups/roles
+// claims) routinely exceed. On Windows we work around this by
+// splitting the JSON blob across multiple entries with account names
+// `credentials.0`, `credentials.1`, … . `CHUNK_LIMIT` leaves margin
+// under the platform cap; `MAX_CHUNKS` is a safety bound — we should
+// never get close in practice, even with maximally-claimed tokens.
+//
+// macOS Keychain and Linux libsecret have no comparable limit, so
+// chunking there would just multiply per-entry ACL prompts (each
+// keychain entry is independently lockable on macOS) for no gain.
+// Chunking is therefore Windows-only, gated by `shouldChunkForKeyring`.
+const CHUNK_LIMIT = 2500;
+const MAX_CHUNKS = 32;
+/**
+ * Whether `KeyringTokenStore` should split the stored blob across
+ * multiple keychain entries on this platform. Windows-only because of
+ * Credential Manager's 2560 UTF-16 character per-entry cap. Exported
+ * (parameterized for tests) so the chunking path can be exercised
+ * deterministically.
+ */
+function shouldChunkForKeyring(platform = process.platform) {
+    return platform === "win32";
+}
 /**
  * Current on-disk blob schema version. Exported so consumers can
  * display "stored v:N, expected v:M" diagnostics when `load()` returns
@@ -153,32 +187,184 @@ 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 });
+    // Pass-through pre-wrapped OAuthFlowErrors so we don't double-wrap
+    // our own error type. The most common source today is
+    // `defaultEntryFactory` throwing `KEYRING_UNAVAILABLE` when the
+    // native binding can't be loaded — relabelling that as another
+    // `KEYRING_UNAVAILABLE` with a duplicate message and a possibly
+    // misleading platform hint helps nobody.
+    if (cause instanceof errors_1.OAuthFlowError) {
+        throw cause;
+    }
+    throw new errors_1.OAuthFlowError("KEYRING_UNAVAILABLE", keyringErrorMessage(op, cause), {
+        cause,
+    });
+}
+/**
+ * Builds the user-facing keychain error message. Platform is a
+ * parameter (defaulting to `process.platform`) so tests can drive each
+ * branch without mocking the runtime; mirrors the pattern in
+ * `platformKeyringHint`.
+ *
+ * The Windows-specific size-limit message is only used when the
+ * underlying error matches the binding's "longer than the platform
+ * limit" wording AND the runtime is win32 — that combination is the
+ * only way the size cap actually manifests in practice. On other
+ * platforms (or for any other binding error) we fall back to the
+ * generic per-platform hint.
+ */
+function keyringErrorMessage(op, cause, platform = process.platform) {
+    if (platform === "win32" && isKeyringSizeError(cause)) {
+        return `System keychain ${op} failed: Windows Credential Manager limits stored values to 2560 UTF-16 characters. Large OAuth access-token JWTs (many groups/roles claims) commonly exceed this.`;
+    }
+    const causeMessage = cause instanceof Error ? cause.message : String(cause);
+    return `System keychain ${op} failed: ${causeMessage}. ${platformKeyringHint(platform)}`;
+}
+/**
+ * Detects the `@napi-rs/keyring` error string for "value too large".
+ * In practice only Windows Credential Manager triggers this — its
+ * stored values are capped at 2560 UTF-16 chars; macOS Keychain and
+ * Linux libsecret have no comparable limit. Exported (but not
+ * re-exported from the package index) so tests can exercise the
+ * detector independently of the wrap path.
+ */
+function isKeyringSizeError(cause) {
+    if (!(cause instanceof Error))
+        return false;
+    return /longer than the platform limit/.test(cause.message);
+}
+/**
+ * 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}.`;
+    }
+}
+/**
+ * Parses chunk 0's `<N>\n<rest>` header. Returns the chunk count and
+ * the data part following the newline, or `null` for any malformed /
+ * out-of-range / non-canonically-encoded header. Centralised here
+ * (rather than open-coded twice in `#loadChunked` and
+ * `#previousChunkN`) so the canonical-encoding contract has one
+ * authoritative implementation.
+ */
+function parseChunkHeader(first) {
+    const newlineIdx = first.indexOf("\n");
+    if (newlineIdx <= 0)
+        return null;
+    const nStr = first.slice(0, newlineIdx);
+    const n = parseInt(nStr, 10);
+    // Reject non-canonical encodings ("01", " 3", "3abc"). parseInt is
+    // permissive about those; we want a single canonical encoding so
+    // two different headers can't decode to the same N.
+    if (!Number.isInteger(n) || n < 1 || n > MAX_CHUNKS || String(n) !== nStr) {
+        return null;
+    }
+    return { n, rest: first.slice(newlineIdx + 1) };
 }
 /**
  * `TokenStore` backed by the operating system's native keychain via
  * `@napi-rs/keyring` (macOS Keychain, Windows Credential Manager, Linux
- * Secret Service). One entry per machine, keyed by a fixed account
- * name; the blob carries its own issuer/client coordinates so verbs
- * can recover full config without per-issuer keying.
+ * Secret Service). On macOS and Linux the blob lives in a single entry
+ * keyed by the fixed `credentials` account name. On Windows the blob
+ * is split across `credentials.0`, `credentials.1`, … entries to fit
+ * under Credential Manager's 2560 UTF-16 character per-entry cap; see
+ * `shouldChunkForKeyring`.
+ *
+ * The blob carries its own issuer/client coordinates so verbs can
+ * recover full config without per-issuer keying.
  */
 class KeyringTokenStore {
-    #entry;
+    #entryFactory;
+    #chunked;
+    /**
+     * @param entryFactory Injection seam for `@napi-rs/keyring` entries.
+     *   Defaults to the production lazy-resolved factory; tests pass a
+     *   recording / faking variant.
+     */
     constructor(entryFactory = keyringBinding_1.defaultEntryFactory) {
-        this.#entry = entryFactory(SERVICE_NAME, ACCOUNT_NAME);
+        this.#entryFactory = entryFactory;
+        this.#chunked = shouldChunkForKeyring();
+    }
+    /**
+     * @internal Test seam. Constructs a store with an explicit chunking
+     * decision instead of the platform-determined default, so the
+     * chunked path can be exercised on macOS/Linux CI and the unchunked
+     * path on Windows CI. Production code must use the regular
+     * constructor and let `shouldChunkForKeyring()` decide — passing
+     * `chunked: true` on macOS would write data that the regular
+     * constructor wouldn't be able to read.
+     */
+    static forTesting(entryFactory, chunked) {
+        const store = new KeyringTokenStore(entryFactory);
+        store.#chunked = chunked;
+        return store;
+    }
+    #entry(account) {
+        return this.#entryFactory(SERVICE_NAME, account);
     }
     async save(entry) {
-        try {
-            this.#entry.setPassword(JSON.stringify(entryToBlob(entry)));
+        const jsonBlob = JSON.stringify(entryToBlob(entry));
+        if (this.#chunked) {
+            // Encode + chunk OUTSIDE the try/catch so a TOKEN_TOO_LARGE from
+            // `chunkBlobForKeyring` surfaces unchanged. The keychain
+            // operations stay inside the try and get wrapped as
+            // KEYRING_UNAVAILABLE if they fail.
+            const encoded = Buffer.from(jsonBlob, "utf8").toString("base64");
+            const parts = chunkBlobForKeyring(encoded);
+            try {
+                this.#saveChunked(parts);
+            }
+            catch (cause) {
+                wrapKeyringError("write", cause);
+            }
         }
-        catch (cause) {
-            wrapKeyringError("write", cause);
+        else {
+            try {
+                this.#entry(ACCOUNT_NAME).setPassword(jsonBlob);
+            }
+            catch (cause) {
+                wrapKeyringError("write", cause);
+            }
         }
     }
     async load() {
         let raw;
         try {
-            raw = this.#entry.getPassword();
+            if (this.#chunked) {
+                const result = this.#loadChunked();
+                if (result.kind === "present") {
+                    raw = result.blob;
+                }
+                else if (result.kind === "empty") {
+                    // First-time-upgrade fallback: a Windows dev who upgraded
+                    // across the chunking change has data at the bare
+                    // `credentials` account but no chunks yet. Read that legacy
+                    // entry; the next save() migrates it. Note we only fall
+                    // back when chunked data is *empty* — when chunked data is
+                    // *corrupt* we surface that directly rather than restoring
+                    // potentially stale legacy data underneath the corruption.
+                    raw = this.#entry(ACCOUNT_NAME).getPassword();
+                }
+                else {
+                    return { ok: false, reason: "corrupt" };
+                }
+            }
+            else {
+                raw = this.#entry(ACCOUNT_NAME).getPassword();
+            }
         }
         catch (cause) {
             wrapKeyringError("read", cause);
@@ -192,11 +378,208 @@ class KeyringTokenStore {
     }
     async clear() {
         try {
-            this.#entry.deletePassword();
+            if (this.#chunked) {
+                this.#clearChunked();
+            }
+            else {
+                this.#entry(ACCOUNT_NAME).deletePassword();
+            }
         }
         catch (cause) {
             wrapKeyringError("delete", cause);
         }
     }
+    /**
+     * Writes `parts` (the output of `chunkBlobForKeyring`) to entries
+     * `credentials.0..N-1`.
+     *
+     * Writes are in **reverse index order** — chunks N-1..1, then chunk
+     * 0 with the new header last. Chunk 0's header is what reads use to
+     * learn N, so until it's overwritten the previous chunk 0 still
+     * references the previous N chunks.
+     *
+     * Crash recovery is partial, not total. Reverse order helps in one
+     * case: when N_new > N_old and the crash happens before chunk 0 is
+     * rewritten — writes to indices >= N_old don't disturb old data,
+     * the previous chunk 0 still references the previous N chunks, and
+     * the prior session survives. The typical refresh case (N_new ==
+     * N_old) overwrites chunks 1..N-1 with new data while chunk 0 is
+     * still old, so a crash there reads as corrupt and the user
+     * re-auths. Reverse order is therefore a marginal improvement over
+     * forward order, not a guarantee.
+     *
+     * Cleanup sweeps `[N_new, N_old)` (bounded by the previous chunk
+     * count read from the old chunk 0 header before we overwrite it).
+     * For a typical token refresh (same N) this is zero deletes; the
+     * full safety sweep up to MAX_CHUNKS only runs as a defensive
+     * recovery when the previous N can't be determined. Orphans at
+     * indices >= max(N_new, N_old) from interrupted resize-up writes
+     * persist until the next `clear()` does the full sweep.
+     *
+     * Concurrency: this method is not safe to run concurrently against
+     * the same OS keychain. Two writers can interleave at chunk
+     * boundaries and produce a Frankenstein blob. axe-auth runs as a
+     * short-lived CLI so this is unlikely in practice, but a long-lived
+     * process refreshing in the background while the CLI is invoked
+     * could trip it.
+     */
+    #saveChunked(parts) {
+        // Read previous N before any writes so the cleanup sweep is
+        // bounded. If the previous chunk 0 is missing or its header is
+        // unparseable we have no upper bound, so fall back to the full
+        // safety range as a one-time defensive recovery.
+        const previousN = this.#previousChunkN();
+        for (let i = parts.length - 1; i >= 1; i--) {
+            this.#entry(`${ACCOUNT_NAME}.${i}`).setPassword(parts[i]);
+        }
+        this.#entry(`${ACCOUNT_NAME}.0`).setPassword(parts[0]);
+        // Best-effort sweep: writes have already succeeded, so a sweep
+        // failure shouldn't roll back the save. The next save's bounded
+        // sweep cleans up anything we miss here. Same reasoning for the
+        // legacy delete below.
+        const sweepEnd = previousN ?? MAX_CHUNKS;
+        for (let i = parts.length; i < sweepEnd; i++) {
+            try {
+                this.#entry(`${ACCOUNT_NAME}.${i}`).deletePassword();
+            }
+            catch {
+                // Sweep is best-effort; the next save handles leftovers.
+            }
+        }
+        // Clear any pre-chunking single-entry blob from a previous
+        // axe-auth release. This is a forever-tax (one extra
+        // deletePassword per save even after the migration is done)
+        // because we have no per-machine "migration completed" flag;
+        // adding one would mean another keychain entry to manage. The
+        // cost is one Credential Manager call per refresh — negligible
+        // relative to the OAuth round-trip.
+        try {
+            this.#entry(ACCOUNT_NAME).deletePassword();
+        }
+        catch {
+            // Best-effort; the next save attempts again.
+        }
+    }
+    /**
+     * Reads the chunk-count header from `credentials.0` so `#saveChunked`
+     * can bound its cleanup sweep. Returns `null` when chunk 0 is
+     * missing, when the header is malformed, or when the encoded N is
+     * out of range — every "I don't know the previous count" case
+     * collapses to a full safety sweep at the call site.
+     */
+    #previousChunkN() {
+        const first = this.#entry(`${ACCOUNT_NAME}.0`).getPassword();
+        if (first === null)
+            return null;
+        return parseChunkHeader(first)?.n ?? null;
+    }
+    /**
+     * Reverse of `#saveChunked`. Returns a discriminated result so the
+     * caller can distinguish "no data" from "data is malformed" without
+     * reaching for sentinel strings.
+     */
+    #loadChunked() {
+        const first = this.#entry(`${ACCOUNT_NAME}.0`).getPassword();
+        if (first === null)
+            return { kind: "empty" };
+        const header = parseChunkHeader(first);
+        if (!header)
+            return { kind: "corrupt" };
+        const parts = [header.rest];
+        for (let i = 1; i < header.n; i++) {
+            const part = this.#entry(`${ACCOUNT_NAME}.${i}`).getPassword();
+            if (part === null)
+                return { kind: "corrupt" };
+            parts.push(part);
+        }
+        // `Buffer.from(_, 'base64')` is permissive — invalid characters
+        // are silently dropped rather than throwing. Garbage base64
+        // produces garbage UTF-8, which falls through to the upstream
+        // JSON.parse and surfaces as `corrupt` from
+        // `parseAndMigrateBlob`. So no try/catch is needed here.
+        const blob = Buffer.from(parts.join(""), "base64").toString("utf8");
+        return { kind: "present", blob };
+    }
+    #clearChunked() {
+        // Sweep the whole safety range rather than break-on-first-missing
+        // so chunk holes (from interrupted writes or manual tampering)
+        // still get cleaned up. Logout is rare enough that the
+        // unconditional sweep cost is irrelevant.
+        //
+        // Per-entry errors are caught locally so a single throw doesn't
+        // strand the remaining chunks (or the legacy entry) in the
+        // keychain. After all attempts, we surface the first failure so
+        // the user still sees that logout didn't fully complete.
+        let firstError = null;
+        for (let i = 0; i < MAX_CHUNKS; i++) {
+            try {
+                this.#entry(`${ACCOUNT_NAME}.${i}`).deletePassword();
+            }
+            catch (cause) {
+                firstError ??= cause;
+            }
+        }
+        // And the pre-chunking single-entry blob, in case a Windows dev
+        // had axe-auth installed before chunking shipped.
+        try {
+            this.#entry(ACCOUNT_NAME).deletePassword();
+        }
+        catch (cause) {
+            firstError ??= cause;
+        }
+        if (firstError !== null) {
+            throw firstError;
+        }
+    }
 }
 exports.KeyringTokenStore = KeyringTokenStore;
+/**
+ * Splits `blob` into the N parts that `KeyringTokenStore.#saveChunked`
+ * writes to `credentials.0..N-1`. Chunk 0 is prefixed with `<N>\n` so
+ * the reader can learn N from a single getPassword call. Each chunk
+ * stays under `CHUNK_LIMIT` UTF-16 characters; throws if the blob would
+ * require more than `MAX_CHUNKS` chunks. Exported for tests.
+ */
+function chunkBlobForKeyring(blob) {
+    // N depends on the header length, which depends on N. Solve by
+    // iterating until the chunk count stabilises (converges in <= a
+    // couple of steps for any realistic blob). The safety counter is
+    // belt-and-suspenders against a future tweak (different
+    // CHUNK_LIMIT, different header format) accidentally introducing
+    // oscillation; an unbounded loop here would hang `axe-auth login`
+    // with no error.
+    let n = Math.max(1, Math.ceil(blob.length / CHUNK_LIMIT));
+    let safety = 0;
+    while (true) {
+        if (++safety > 8) {
+            throw new Error(`chunkBlobForKeyring: chunk count failed to converge after ${safety} iterations (blob length ${blob.length})`);
+        }
+        const headerLen = String(n).length + 1; // "<N>\n"
+        const chunk0Capacity = CHUNK_LIMIT - headerLen;
+        if (chunk0Capacity <= 0) {
+            throw new Error(`chunkBlobForKeyring: chunk count ${n} leaves no room for data`);
+        }
+        const remaining = Math.max(0, blob.length - chunk0Capacity);
+        const next = 1 + Math.ceil(remaining / CHUNK_LIMIT);
+        if (next === n)
+            break;
+        n = next;
+    }
+    if (n > MAX_CHUNKS) {
+        // Surfaced as a distinct error code (rather than KEYRING_UNAVAILABLE)
+        // because the keystore is healthy — the failure is that the IDP's
+        // token has too many claims to fit. Wrapping this as a keychain
+        // error would attach a misleading "Credential Manager rejected"
+        // platform hint via `wrapKeyringError`'s default path.
+        throw new errors_1.OAuthFlowError("TOKEN_TOO_LARGE", `OAuth token blob would require ${n} keyring entries (max ${MAX_CHUNKS}). The IDP may be issuing tokens with unusually many claims; talk to the realm administrator.`);
+    }
+    const headerLen = String(n).length + 1;
+    const chunk0Capacity = CHUNK_LIMIT - headerLen;
+    const parts = [`${n}\n${blob.slice(0, chunk0Capacity)}`];
+    let pos = chunk0Capacity;
+    while (pos < blob.length) {
+        parts.push(blob.slice(pos, pos + CHUNK_LIMIT));
+        pos += CHUNK_LIMIT;
+    }
+    return parts;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deque/axe-auth",
-  "version": "1.1.0-next.487d00fa",
+  "version": "1.1.0-next.49c17a1d",
   "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.16",
     "tsx": "^4.20.6",
     "typescript": "^5.9.3"
   },