@deque/axe-auth 1.1.0-next.ac35e028 → 1.1.0-next.ace85bdc

package/dist/oauth/tokenStore.d.ts

@@ -1,5 +1,16 @@
 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: Credential
+ * Manager has a 2560-byte per-entry cap that large OAuth tokens
+ * routinely exceed. macOS Keychain and Linux libsecret have no
+ * comparable limit, and on macOS each entry is independently lockable
+ * (chunking there would multiply per-entry ACL prompts). 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
@@ -21,6 +32,11 @@ export interface StoredEntry {
     clientId: string;
     /** Whether the original login allowed a non-loopback http issuer. */
     allowInsecureIssuer: boolean;
+    /**
+     * Originating axe server (walnut) URL the user supplied (or the
+     * SaaS prod default) at login.
+     */
+    walnutURL: string;
 }
 /**
  * Outcome of a `TokenStore.load()` call.
@@ -95,17 +111,61 @@ 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: the underlying
+ * cause's text plus a per-platform hint. Platform is a parameter
+ * (defaulting to `process.platform`) so tests can drive each branch
+ * without mocking the runtime; mirrors the pattern in
+ * `platformKeyringHint`.
+ */
+export declare function keyringErrorMessage(op: string, cause: unknown, platform?: NodeJS.Platform): string;
+/**
+ * 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-byte (1280 UTF-16 char) 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,24 +1,50 @@
 "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.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.
-// On Windows: Credential Manager entry. On Linux: Secret Service / libsecret.
-// 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.
-//
-// 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.
+/**
+ * Keychain account identifier. On macOS/Linux the entire blob lives at
+ * this single account. On Windows the blob is base64-encoded and split
+ * across `credentials.0`, `credentials.1`, … entries (see `CHUNK_LIMIT`),
+ * so a Windows dev inspecting Credential Manager will see opaque base64.
+ */
 const ACCOUNT_NAME = "credentials";
+/**
+ * Max JS string length per chunk. The limit applies to the full chunk
+ * including chunk 0's `<N>\n` count header, so chunk 0's data slice is
+ * `CHUNK_LIMIT - headerLen`. Windows Credential Manager's per-entry
+ * cap is `CRED_MAX_CREDENTIAL_BLOB_SIZE = 2560` bytes, and the
+ * `@napi-rs/keyring` Windows backend stores strings as UTF-16 (2 bytes
+ * per char), so 1250 chars = 2500 bytes stays safely under the cap.
+ */
+const CHUNK_LIMIT = 1250;
+/**
+ * Cap on chunks per stored blob. A request that would exceed this
+ * raises `TOKEN_TOO_LARGE` so an IDP issuing tokens with extraordinary
+ * claim counts fails with a clear error instead of silently consuming
+ * dozens of keychain entries.
+ */
+const MAX_CHUNKS = 32;
+/**
+ * Whether `KeyringTokenStore` should split the stored blob across
+ * multiple keychain entries on this platform. Windows-only: Credential
+ * Manager has a 2560-byte per-entry cap that large OAuth tokens
+ * routinely exceed. macOS Keychain and Linux libsecret have no
+ * comparable limit, and on macOS each entry is independently lockable
+ * (chunking there would multiply per-entry ACL prompts). 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
@@ -72,7 +98,9 @@ function isLatestBlob(blob) {
         (b.refreshToken === undefined || typeof b.refreshToken === "string") &&
         typeof b.issuerURL === "string" &&
         typeof b.clientId === "string" &&
-        typeof b.allowInsecureIssuer === "boolean");
+        typeof b.allowInsecureIssuer === "boolean" &&
+        typeof b.walnutURL === "string" &&
+        b.walnutURL.length > 0);
 }
 function blobToEntry(blob) {
     const tokens = {
@@ -86,6 +114,7 @@ function blobToEntry(blob) {
         issuerURL: blob.issuerURL,
         clientId: blob.clientId,
         allowInsecureIssuer: blob.allowInsecureIssuer,
+        walnutURL: blob.walnutURL,
     };
 }
 function entryToBlob(entry) {
@@ -96,6 +125,7 @@ function entryToBlob(entry) {
         issuerURL: entry.issuerURL,
         clientId: entry.clientId,
         allowInsecureIssuer: entry.allowInsecureIssuer,
+        walnutURL: entry.walnutURL,
     };
     if (entry.tokens.refreshToken)
         blob.refreshToken = entry.tokens.refreshToken;
@@ -122,10 +152,6 @@ function parseAndMigrateBlob(raw, expectedVersion = exports.STORED_BLOB_VERSION,
     const storedVersion = getStoredVersion(parsed);
     if (storedVersion === null)
         return { ok: false, reason: "corrupt" };
-    // Walk the migrator chain until we reach the expected version. A
-    // missing or null-returning migrator means the old blob cannot be
-    // upgraded; surface that so callers can prompt re-auth with a
-    // clear signal instead of silently returning `empty`.
     let current = parsed;
     let currentVersion = storedVersion;
     while (currentVersion !== expectedVersion) {
@@ -139,8 +165,6 @@ function parseAndMigrateBlob(raw, expectedVersion = exports.STORED_BLOB_VERSION,
         }
         const nextVersion = getStoredVersion(next);
         if (nextVersion === null || nextVersion <= currentVersion) {
-            // Migrator output is malformed or didn't advance. Treat the
-            // stored blob as un-migratable rather than loop forever.
             return { ok: false, reason: "version-mismatch", storedVersion };
         }
         current = next;
@@ -149,32 +173,162 @@ 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: the underlying
+ * cause's text plus a per-platform hint. Platform is a parameter
+ * (defaulting to `process.platform`) so tests can drive each branch
+ * without mocking the runtime; mirrors the pattern in
+ * `platformKeyringHint`.
+ */
+function keyringErrorMessage(op, cause, platform = process.platform) {
+    const causeMessage = cause instanceof Error ? cause.message : String(cause);
+    return `System keychain ${op} failed: ${causeMessage}. ${platformKeyringHint(platform)}`;
+}
+/**
+ * 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-byte (1280 UTF-16 char) 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);
@@ -188,11 +342,204 @@ 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) {
+        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/dist/userAgent.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `User-Agent` header value sent on all outbound requests, per
+ * Service Development Standards §4.4.
+ *
+ * Format: `axe-auth/v<package-version>` (e.g. `axe-auth/v1.0.2`).
+ *
+ * The npm scope (`@deque/`) is deliberately omitted from the wire format:
+ * `@` and `/` are not valid `tchar` per RFC 9110 §5.6.2, so a token like
+ * `@deque/axe-auth` would make the User-Agent malformed and risk WAF
+ * rejection (e.g. OWASP CRS rule 920330).
+ */
+export declare const USER_AGENT: string;

package/dist/userAgent.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.USER_AGENT = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const pkg = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, "..", "package.json"), "utf-8"));
+/**
+ * `User-Agent` header value sent on all outbound requests, per
+ * Service Development Standards §4.4.
+ *
+ * Format: `axe-auth/v<package-version>` (e.g. `axe-auth/v1.0.2`).
+ *
+ * The npm scope (`@deque/`) is deliberately omitted from the wire format:
+ * `@` and `/` are not valid `tchar` per RFC 9110 §5.6.2, so a token like
+ * `@deque/axe-auth` would make the User-Agent malformed and risk WAF
+ * rejection (e.g. OWASP CRS rule 920330).
+ */
+exports.USER_AGENT = `axe-auth/v${pkg.version}`;