@deque/axe-auth 1.1.0-next.97bcb8e6 → 1.1.0-next.9c8d8c98

package/dist/oauth/tokenExchange.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exchangeCodeForTokens = exchangeCodeForTokens;
+const errors_1 = require("./errors");
+const tokenResponse_1 = require("./tokenResponse");
+const userAgent_1 = require("../userAgent");
+/**
+ * Exchanges an authorization code for a `TokenSet` via the
+ * authorization server's token endpoint (RFC 6749 §4.1.3 + RFC 7636
+ * §4.5). Rejects with `OAuthFlowError("TOKEN_EXCHANGE_FAILED", ...)`
+ * for any failure mode, surfacing the OAuth `error` /
+ * `error_description` when available.
+ */
+async function exchangeCodeForTokens(options) {
+    const now = options.now ?? Date.now;
+    const body = new URLSearchParams({
+        grant_type: "authorization_code",
+        client_id: options.clientId,
+        code: options.code,
+        code_verifier: options.codeVerifier,
+        redirect_uri: options.redirectUri,
+    });
+    const issuedAt = now();
+    let response;
+    try {
+        response = await fetch(options.tokenEndpoint, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+                Accept: "application/json",
+                "User-Agent": userAgent_1.USER_AGENT,
+            },
+            body,
+            signal: options.signal,
+        });
+    }
+    catch (cause) {
+        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Could not reach the token endpoint at ${options.tokenEndpoint}. Check your network connection.`, { cause });
+    }
+    if (!response.ok) {
+        await (0, tokenResponse_1.throwTokenEndpointError)(response, "Token exchange");
+    }
+    return (0, tokenResponse_1.parseTokenResponse)(response, issuedAt, options.tokenEndpoint);
+}

package/dist/oauth/tokenResponse.d.ts

@@ -0,0 +1,22 @@
+/** Tokens returned by a successful token-endpoint call. */
+export interface TokenSet {
+    /** Access token for authenticated API calls. */
+    accessToken: string;
+    /** Long-lived token used to mint new access tokens without re-auth. Absent if the flow did not return one. */
+    refreshToken?: string;
+    /** Absolute timestamp (ms since epoch) when the access token expires. */
+    expiresAt: number;
+    /** Space-delimited scopes the server actually granted, if reported. */
+    grantedScope?: string;
+}
+/**
+ * Reads a non-2xx response body and throws `TOKEN_EXCHANGE_FAILED`
+ * with the OAuth `error` / `error_description` surfaced when present.
+ */
+export declare function throwTokenEndpointError(response: Response, context: string): Promise<never>;
+/**
+ * Parses a 2xx response from an RFC 6749 §5.1 token endpoint into a
+ * `TokenSet`. `issuedAt` is the timestamp captured just before the
+ * network call; the resulting `expiresAt` is conservative by ~RTT.
+ */
+export declare function parseTokenResponse(response: Response, issuedAt: number, endpointURL: string): Promise<TokenSet>;

package/dist/oauth/tokenResponse.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.throwTokenEndpointError = throwTokenEndpointError;
+exports.parseTokenResponse = parseTokenResponse;
+const errors_1 = require("./errors");
+const predicates_1 = require("./predicates");
+// RFC 6749 §5.1 doesn't pin the JSON type and some providers send
+// numeric strings; accept both, reject non-positive or non-finite.
+function parseExpiresIn(v) {
+    if (typeof v === "number" && Number.isFinite(v) && v > 0)
+        return v;
+    if (typeof v === "string") {
+        const n = Number(v);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return null;
+}
+function parseErrorBody(body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return {};
+    }
+    if (parsed === null || typeof parsed !== "object")
+        return {};
+    const raw = parsed;
+    return {
+        error: (0, predicates_1.isNonEmptyString)(raw.error) ? raw.error : undefined,
+        description: (0, predicates_1.isNonEmptyString)(raw.error_description)
+            ? raw.error_description
+            : undefined,
+    };
+}
+/**
+ * Reads a non-2xx response body and throws `TOKEN_EXCHANGE_FAILED`
+ * with the OAuth `error` / `error_description` surfaced when present.
+ */
+async function throwTokenEndpointError(response, context) {
+    const body = await response.text().catch(() => "");
+    const { error, description } = parseErrorBody(body);
+    const suffix = error
+        ? description
+            ? `: ${error}: ${description}`
+            : `: ${error}`
+        : "";
+    const details = {};
+    if (error)
+        details.error = error;
+    if (description)
+        details.error_description = description;
+    throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `${context} failed with HTTP ${response.status}${suffix}`, Object.keys(details).length > 0 ? { details } : undefined);
+}
+/**
+ * Parses a 2xx response from an RFC 6749 §5.1 token endpoint into a
+ * `TokenSet`. `issuedAt` is the timestamp captured just before the
+ * network call; the resulting `expiresAt` is conservative by ~RTT.
+ */
+async function parseTokenResponse(response, issuedAt, endpointURL) {
+    let parsed;
+    try {
+        parsed = await response.json();
+    }
+    catch (cause) {
+        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Token endpoint at ${endpointURL} returned a non-JSON response`, { cause });
+    }
+    if (parsed === null || typeof parsed !== "object") {
+        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Token endpoint at ${endpointURL} returned a non-object response`);
+    }
+    const raw = parsed;
+    if (!(0, predicates_1.isNonEmptyString)(raw.access_token)) {
+        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Token response missing 'access_token'`);
+    }
+    const expiresIn = parseExpiresIn(raw.expires_in);
+    if (expiresIn === null) {
+        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Token response missing or has invalid 'expires_in'`);
+    }
+    // RFC 6749 §5.1: token_type is REQUIRED. We only speak Bearer;
+    // DPoP / MAC / other proof-of-possession types need request-side
+    // support we don't implement, and silently treating them as Bearer
+    // would send tokens in the wrong header with unclear semantics.
+    if (!(0, predicates_1.isNonEmptyString)(raw.token_type)) {
+        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Token response missing required 'token_type'`);
+    }
+    if (raw.token_type.toLowerCase() !== "bearer") {
+        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Unsupported token_type '${raw.token_type}'; this library only handles Bearer.`);
+    }
+    const tokens = {
+        accessToken: raw.access_token,
+        expiresAt: issuedAt + expiresIn * 1000,
+    };
+    if ((0, predicates_1.isNonEmptyString)(raw.refresh_token)) {
+        tokens.refreshToken = raw.refresh_token;
+    }
+    if ((0, predicates_1.isNonEmptyString)(raw.scope)) {
+        tokens.grantedScope = raw.scope;
+    }
+    return tokens;
+}

package/dist/oauth/tokenStore.d.ts

@@ -0,0 +1,171 @@
+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
+ * a `version-mismatch` result.
+ */
+export declare const STORED_BLOB_VERSION = 1;
+/**
+ * What `KeyringTokenStore` persists: the OAuth tokens plus the
+ * issuer/client coordinates they were minted against. Carrying the
+ * coordinates inside the entry means a verb can recover its full
+ * config from the keychain alone, with no separate "default issuer"
+ * pointer.
+ */
+export interface StoredEntry {
+    tokens: TokenSet;
+    /** OIDC issuer URL the tokens were minted against. */
+    issuerURL: string;
+    /** OAuth client ID used at login. */
+    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.
+ *
+ * Note on downgrades: the migrator chain only walks *forward*. A user
+ * who downgrades `axe-auth` to a release that predates a schema bump
+ * will see `version-mismatch` on any blob written by the newer
+ * release, even if the change was strictly additive. That is the safe
+ * default for a credentials blob — the older version cannot vouch for
+ * the meaning of fields it has never seen. Callers hitting this case
+ * should treat it as "re-authenticate" rather than attempting to
+ * parse an unknown future shape.
+ */
+export type LoadResult = {
+    ok: true;
+    entry: StoredEntry;
+} | {
+    ok: false;
+    reason: "empty";
+} | {
+    ok: false;
+    reason: "corrupt";
+} | {
+    ok: false;
+    reason: "version-mismatch";
+    storedVersion: number;
+};
+/** Persistence layer for an OAuth `StoredEntry`. */
+export interface TokenStore {
+    /** Write-through save. Replaces any previously stored entry. */
+    save(entry: StoredEntry): Promise<void>;
+    /**
+     * Reads the stored entry and returns a structured result.
+     *
+     * Callers should branch on `result.ok` first. When `ok` is `false`,
+     * `reason` tells them *why* there is no usable entry: `empty`
+     * (nothing stored), `corrupt` (unparseable or shape-invalid), or
+     * `version-mismatch` (stored under a schema we cannot migrate from).
+     * The library does not emit output on these cases — surfacing them
+     * to the user is the caller's responsibility.
+     */
+    load(): Promise<LoadResult>;
+    /** Removes any stored entry. No-op if none is present. */
+    clear(): Promise<void>;
+}
+/**
+ * Outcome of `parseAndMigrateBlob`: same set of failure reasons as
+ * `LoadResult`, but on success carries the post-migration blob as an
+ * unknown payload. The caller is responsible for shape-validating
+ * that payload against the latest schema.
+ */
+export type BlobChainResult = {
+    ok: true;
+    blob: unknown;
+} | {
+    ok: false;
+    reason: "empty";
+} | {
+    ok: false;
+    reason: "corrupt";
+} | {
+    ok: false;
+    reason: "version-mismatch";
+    storedVersion: number;
+};
+/**
+ * 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.
+ */
+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). 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[];