@deque/axe-auth 1.1.0-next.fb07beab → 1.1.0-next.fea0aa8a

package/dist/oauth/tokenStore.js

@@ -0,0 +1,560 @@
+"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");
+const SERVICE_NAME = "axe-auth";
+// On Windows the blob is base64-encoded and split across
+// `credentials.0`, `credentials.1`, … entries (see `CHUNK_LIMIT`); a
+// Windows dev inspecting Credential Manager will see opaque base64.
+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
+ * a `version-mismatch` result.
+ */
+exports.STORED_BLOB_VERSION = 1;
+/**
+ * Migrators upgrade an older blob to the next version up. Walked by
+ * `load()` until the stored blob reaches `STORED_BLOB_VERSION`.
+ *
+ * A migrator returns `null` when the bump cannot be inferred from the
+ * old shape (e.g. a new required field with no derivable default); the
+ * caller then sees `{ ok: false, reason: "version-mismatch" }` and
+ * decides whether to re-auth, prompt, or preserve the old blob.
+ *
+ * Each migrator is responsible for taking `vN` → `vN+1`. To skip a
+ * version deliberately, register a migrator that returns `null` for
+ * that `fromVersion`.
+ */
+const MIGRATORS = new Map([
+// [1, (v1) => migrateV1ToV2(v1 as StoredBlobV1)],
+]);
+// Sanity-check the migrator map at module load. Every key must be
+// strictly less than `STORED_BLOB_VERSION` — the chain only walks
+// forward, so a leftover migrator at the current (or future) version
+// would either be unreachable or confuse the loop. Fail-fast so a
+// dev forgetting to remove a stale entry during a version bump
+// notices before shipping.
+for (const fromVersion of MIGRATORS.keys()) {
+    if (fromVersion >= exports.STORED_BLOB_VERSION) {
+        throw new Error(`MIGRATORS contains a key (v${fromVersion}) that is not strictly less than STORED_BLOB_VERSION (${exports.STORED_BLOB_VERSION}). The chain only walks forward; remove stale migrators when bumping the schema version.`);
+    }
+}
+function getStoredVersion(blob) {
+    if (blob === null || typeof blob !== "object")
+        return null;
+    const v = blob.v;
+    return typeof v === "number" && Number.isInteger(v) && v > 0 ? v : null;
+}
+function isLatestBlob(blob) {
+    if (blob === null || typeof blob !== "object")
+        return false;
+    const b = blob;
+    return (b.v === exports.STORED_BLOB_VERSION &&
+        // Empty access token is treated as corrupt rather than a usable
+        // credential. `axe-auth token` printing an empty line and exiting
+        // 0 would look like success and silently break downstream.
+        typeof b.accessToken === "string" &&
+        b.accessToken.length > 0 &&
+        typeof b.expiresAt === "number" &&
+        (b.refreshToken === undefined || typeof b.refreshToken === "string") &&
+        typeof b.issuerURL === "string" &&
+        typeof b.clientId === "string" &&
+        typeof b.allowInsecureIssuer === "boolean" &&
+        typeof b.walnutURL === "string" &&
+        b.walnutURL.length > 0);
+}
+function blobToEntry(blob) {
+    const tokens = {
+        accessToken: blob.accessToken,
+        expiresAt: blob.expiresAt,
+    };
+    if (blob.refreshToken)
+        tokens.refreshToken = blob.refreshToken;
+    return {
+        tokens,
+        issuerURL: blob.issuerURL,
+        clientId: blob.clientId,
+        allowInsecureIssuer: blob.allowInsecureIssuer,
+        walnutURL: blob.walnutURL,
+    };
+}
+function entryToBlob(entry) {
+    const blob = {
+        v: exports.STORED_BLOB_VERSION,
+        accessToken: entry.tokens.accessToken,
+        expiresAt: entry.tokens.expiresAt,
+        issuerURL: entry.issuerURL,
+        clientId: entry.clientId,
+        allowInsecureIssuer: entry.allowInsecureIssuer,
+        walnutURL: entry.walnutURL,
+    };
+    if (entry.tokens.refreshToken)
+        blob.refreshToken = entry.tokens.refreshToken;
+    return blob;
+}
+/**
+ * JSON-parses the raw keychain password and walks the migrator chain
+ * until it reaches `expectedVersion`. Exported with `expectedVersion`
+ * and `migrators` parameters only for testing the chain mechanics
+ * against synthetic versions / migrators; production callers use
+ * `KeyringTokenStore.load()`, which feeds in `STORED_BLOB_VERSION`
+ * and `MIGRATORS` and applies the latest-shape check on top.
+ */
+function parseAndMigrateBlob(raw, expectedVersion = exports.STORED_BLOB_VERSION, migrators = MIGRATORS) {
+    if (raw === null)
+        return { ok: false, reason: "empty" };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, reason: "corrupt" };
+    }
+    const storedVersion = getStoredVersion(parsed);
+    if (storedVersion === null)
+        return { ok: false, reason: "corrupt" };
+    let current = parsed;
+    let currentVersion = storedVersion;
+    while (currentVersion !== expectedVersion) {
+        const migrator = migrators.get(currentVersion);
+        if (!migrator) {
+            return { ok: false, reason: "version-mismatch", storedVersion };
+        }
+        const next = migrator(current);
+        if (next === null) {
+            return { ok: false, reason: "version-mismatch", storedVersion };
+        }
+        const nextVersion = getStoredVersion(next);
+        if (nextVersion === null || nextVersion <= currentVersion) {
+            return { ok: false, reason: "version-mismatch", storedVersion };
+        }
+        current = next;
+        currentVersion = nextVersion;
+    }
+    return { ok: true, blob: current };
+}
+function wrapKeyringError(op, 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). 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 {
+    #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.#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) {
+        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);
+            }
+        }
+        else {
+            try {
+                this.#entry(ACCOUNT_NAME).setPassword(jsonBlob);
+            }
+            catch (cause) {
+                wrapKeyringError("write", cause);
+            }
+        }
+    }
+    async load() {
+        let raw;
+        try {
+            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);
+        }
+        const chain = parseAndMigrateBlob(raw);
+        if (!chain.ok)
+            return chain;
+        if (!isLatestBlob(chain.blob))
+            return { ok: false, reason: "corrupt" };
+        return { ok: true, entry: blobToEntry(chain.blob) };
+    }
+    async clear() {
+        try {
+            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}`;