@deque/axe-auth 1.1.0-next.907ffbd7 → 1.1.0-next.ac35e028

package/dist/index.js

@@ -1,47 +1,167 @@
 #!/usr/bin/env node
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-const node_util_1 = require("node:util");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const node_util_1 = require("node:util");
+const ts_dedent_1 = require("ts-dedent");
+const commonArgs_1 = require("./cli/commonArgs");
+const tokenStore_1 = require("./oauth/tokenStore");
+const login_1 = __importDefault(require("./commands/login"));
+const logout_1 = __importDefault(require("./commands/logout"));
+const token_1 = __importDefault(require("./commands/token"));
+const errors_1 = require("./cli/errors");
 const pkg = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, "..", "package.json"), "utf-8"));
-const helpText = `${pkg.name} v${pkg.version}
+// Iteration order is the order verbs appear in `axe-auth --help`.
+const COMMANDS = [
+    login_1.default,
+    logout_1.default,
+    token_1.default,
+];
+function findCommand(verb) {
+    return COMMANDS.find((c) => c.name === verb);
+}
+function topLevelHelp() {
+    const width = Math.max(...COMMANDS.map((c) => c.name.length));
+    const verbList = COMMANDS.map((c) => `  ${c.name.padEnd(width)}  ${c.summary}`).join("\n");
+    return `${pkg.name} v${pkg.version}
 
 ${pkg.description}
 
 Usage:
-  axe-auth [options]
+  axe-auth <command> [options]
+
+Commands:
+${verbList}
+
+Run \`axe-auth <command> --help\` for command-specific options.
 
-Options:
-  -v, --version  Show version number
-  -h, --help     Show this help message`;
-const main = async () => {
-    let values;
+Top-level options:
+  -v, --version  Show version number.
+  -h, --help     Show this help.`;
+}
+async function dispatch(argv) {
+    const [first, ...rest] = argv;
+    if (first === undefined || first === "-h" || first === "--help") {
+        process.stdout.write(`${topLevelHelp()}\n`);
+        return 0;
+    }
+    if (first === "-v" || first === "--version") {
+        process.stdout.write(`${pkg.version}\n`);
+        return 0;
+    }
+    if (first.startsWith("-")) {
+        process.stderr.write(`Unknown option: ${first}. Run \`axe-auth --help\` for usage.\n`);
+        return 2;
+    }
+    const command = findCommand(first);
+    if (!command) {
+        process.stderr.write(`Unknown command: ${first}. Run \`axe-auth --help\` for usage.\n`);
+        return 2;
+    }
+    let parsed;
     try {
-        ({ values } = (0, node_util_1.parseArgs)({
+        parsed = (0, node_util_1.parseArgs)({
+            args: rest,
             options: {
-                version: { type: "boolean", short: "v" },
+                ...commonArgs_1.COMMON_OPTIONS,
+                ...command.options,
                 help: { type: "boolean", short: "h" },
             },
             strict: true,
-        }));
+            allowPositionals: false,
+        });
     }
     catch (err) {
-        console.error(err.message);
-        return 1;
+        process.stderr.write(`${(0, errors_1.describeError)(err)}\n`);
+        return 2;
     }
-    if (values.version) {
-        console.log(pkg.version);
+    if (parsed.values.help) {
+        process.stdout.write(`${command.helpText}\n`);
         return 0;
     }
-    if (values.help) {
-        console.log(helpText);
+    // Best-effort load of the stored config — but only when at least
+    // one common field is unspecified. The dispatcher's fallback is
+    // all-or-nothing (parseCommonArgs ignores defaults if any flag/env
+    // is set), so a fully-flagged invocation gains nothing from a
+    // keychain hit on the hot path.
+    //
+    // The load failure isn't fatal on its own — if the user passed
+    // flags/env, the stored config doesn't matter — but if
+    // `parseCommonArgs` then throws `MissingConfigError`, we surface
+    // this failure alongside it so the user understands the keychain
+    // (not just missing flags) is the proximate cause.
+    let defaults = null;
+    let defaultLoadError = null;
+    let loadedEntry;
+    const commonValues = parsed.values;
+    const allFlagsPresent = Boolean(commonValues.server && commonValues.realm && commonValues["client-id"]);
+    if (!allFlagsPresent) {
+        try {
+            loadedEntry = await new tokenStore_1.KeyringTokenStore().load();
+            if (loadedEntry.ok) {
+                defaults = {
+                    issuerURL: loadedEntry.entry.issuerURL,
+                    clientId: loadedEntry.entry.clientId,
+                    allowInsecureIssuer: loadedEntry.entry.allowInsecureIssuer,
+                };
+            }
+        }
+        catch (err) {
+            defaultLoadError = err;
+        }
+    }
+    let common;
+    try {
+        common = (0, commonArgs_1.parseCommonArgs)(commonValues, process.env, defaults);
+    }
+    catch (err) {
+        if (err instanceof errors_1.MissingConfigError && !command.requiresConfig) {
+            // The verb operates on the stored entry alone (token,
+            // logout). It has its own handling for the empty / corrupt /
+            // version-mismatch cases, which is friendlier than the
+            // generic "missing required configuration" error
+            // (`No stored credentials. Run \`axe-auth login\` first.` for
+            // token; `Already logged out.` for logout). Pass a
+            // sentinel-empty CommonArgs so the verb runs and decides.
+            common = { issuerURL: "", clientId: "", allowInsecureIssuer: false };
+        }
+        else if (err instanceof errors_1.MissingConfigError && defaultLoadError !== null) {
+            process.stderr.write((0, ts_dedent_1.dedent) `
+        ${err.message}
+        Could not read the stored credentials from the keychain (${(0, errors_1.describeError)(defaultLoadError)});
+        pass the flags explicitly or fix the keychain.
+      ` + "\n");
+            return 2;
+        }
+        else {
+            process.stderr.write(`${(0, errors_1.describeError)(err)}\n`);
+            return 2;
+        }
+    }
+    const deps = {
+        stdin: process.stdin,
+        stdout: process.stdout,
+        stderr: process.stderr,
+        loadedEntry,
+    };
+    try {
+        await command.run({ ...common, ...parsed.values }, deps);
         return 0;
     }
-    console.log("No arguments provided. Use --help for usage information.");
-    return 1;
-};
-main().then((code) => process.exit(code), (err) => {
-    console.error(err);
+    catch (err) {
+        if (err instanceof errors_1.CLIError) {
+            process.stderr.write(`${err.message}\n`);
+            return err.exitCode;
+        }
+        process.stderr.write(`${(0, errors_1.describeError)(err)}\n`);
+        return 2;
+    }
+}
+dispatch(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
+    process.stderr.write(`${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`);
     process.exit(1);
 });

package/dist/oauth/authorize.d.ts

@@ -1,4 +1,4 @@
-import { type TokenSet } from "./tokenExchange";
+import type { TokenSet } from "./tokenResponse";
 import { type TokenStore } from "./tokenStore";
 /** Options for `authorize`. */
 export interface AuthorizeOptions {
@@ -25,8 +25,9 @@ export interface AuthorizeOptions {
     /** Aborts the in-flight discovery, callback wait, and token exchange. */
     signal?: AbortSignal;
     /**
-     * Override for the token persistence layer. Defaults to
-     * `KeyringTokenStore` keyed by the normalized issuer URL.
+     * Override for the token persistence layer. Defaults to a fresh
+     * `KeyringTokenStore()` (single keychain entry per machine; the
+     * blob carries its own issuer/client coordinates).
      */
     tokenStore?: TokenStore;
     /** Override for the system browser launcher. Injected for tests. */

package/dist/oauth/authorize.js

@@ -38,7 +38,7 @@ function defaultOnWarning(message) {
  * @throws {OAuthCallbackError} For loopback/callback-server failures.
  */
 async function authorize(options) {
-    const { issuerURL, clientId, scopes, timeoutMs, signal, tokenStore = new tokenStore_1.KeyringTokenStore(issuerURL), openBrowser = openBrowser_1.openBrowser, onAuthorizationUrl = defaultOnAuthorizationUrl, onWarning = defaultOnWarning, allowInsecureIssuer, } = options;
+    const { issuerURL, clientId, scopes, timeoutMs, signal, tokenStore = new tokenStore_1.KeyringTokenStore(), openBrowser = openBrowser_1.openBrowser, onAuthorizationUrl = defaultOnAuthorizationUrl, onWarning = defaultOnWarning, allowInsecureIssuer, } = options;
     // Discovery first. If the auth server is unreachable we want to fail
     // *before* opening a browser — a rejected discovery throw is
     // strictly more useful than a browser tab pointing at a
@@ -98,14 +98,18 @@ async function authorize(options) {
         // came back, warn. Prefer the server's reported `grantedScope`
         // when present (RFC 6749 §5.1) since the provider's consent
         // screen may have dropped the scope.
-        if (scopes.includes("offline_access") &&
-            tokens.refreshToken === undefined) {
+        if (scopes.includes("offline_access") && !tokens.refreshToken) {
             const grantedSuffix = tokens.grantedScope
                 ? ` (server granted: ${tokens.grantedScope})`
                 : "";
             onWarning(`'offline_access' was requested but no refresh_token was returned${grantedSuffix}. Cross-session refresh will not be available.`);
         }
-        await tokenStore.save(tokens);
+        await tokenStore.save({
+            tokens,
+            issuerURL,
+            clientId,
+            allowInsecureIssuer: allowInsecureIssuer ?? false,
+        });
         return tokens;
     }
     finally {

package/dist/oauth/discoverOIDC.js

@@ -3,12 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.discoverOIDC = discoverOIDC;
 const errors_1 = require("./errors");
 const issuerURL_1 = require("./issuerURL");
+const predicates_1 = require("./predicates");
 const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
-function isNonEmptyString(v) {
-    return typeof v === "string" && v.length > 0;
-}
 function optionalString(v) {
-    return isNonEmptyString(v) ? v : undefined;
+    return (0, predicates_1.isNonEmptyString)(v) ? v : undefined;
 }
 /**
  * Throws `DISCOVERY_FAILED` if `url` is not safe to transmit OAuth
@@ -53,12 +51,12 @@ function buildDiscoveryURL(issuerURL) {
 }
 function parseConfiguration(body, url) {
     const missing = [];
-    if (!isNonEmptyString(body.issuer))
+    if (!(0, predicates_1.isNonEmptyString)(body.issuer))
         missing.push("issuer");
-    if (!isNonEmptyString(body.authorization_endpoint)) {
+    if (!(0, predicates_1.isNonEmptyString)(body.authorization_endpoint)) {
         missing.push("authorization_endpoint");
     }
-    if (!isNonEmptyString(body.token_endpoint))
+    if (!(0, predicates_1.isNonEmptyString)(body.token_endpoint))
         missing.push("token_endpoint");
     if (missing.length > 0) {
         throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `OpenID configuration at ${url} is missing required field(s): ${missing.join(", ")}`);

package/dist/oauth/errors.d.ts

@@ -42,7 +42,9 @@ export type OAuthFlowErrorCode =
 /** System keychain is unavailable (e.g. no D-Bus secret service on Linux). */
  | "KEYRING_UNAVAILABLE"
 /** Authorization endpoint returned by discovery cannot be used (e.g. already carries an OAuth-required param). Server misconfiguration. */
- | "INVALID_AUTHORIZATION_ENDPOINT";
+ | "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. */
+ | "NOT_AUTHENTICATED";
 /** Options for `OAuthFlowError`. */
 export interface OAuthFlowErrorOptions {
     /** Structured metadata for callers that want to surface specific fields. */

package/dist/oauth/getValidAccessToken.d.ts

@@ -0,0 +1,89 @@
+import { type LoadResult, type TokenStore } from "./tokenStore";
+/** Options for `getValidAccessToken`. */
+export interface GetValidAccessTokenOptions {
+    /**
+     * OIDC issuer URL (same value passed to `authorize`). Must match
+     * the stored entry's `issuerURL`; mismatch throws
+     * `OAuthFlowError("NOT_AUTHENTICATED", ...)` rather than refreshing
+     * the wrong issuer's tokens at the requested endpoint.
+     */
+    issuerURL: string;
+    /**
+     * OAuth client identifier. Must match the stored entry's
+     * `clientId`; see the note on `issuerURL` for the mismatch
+     * behavior.
+     */
+    clientId: string;
+    /**
+     * How close to expiry we start preemptively refreshing, in
+     * milliseconds. Defaults to 60_000 (60s). The buffer gives headroom
+     * between our "still fresh enough" check and the server's view of
+     * expiry (which may differ by a few seconds of clock skew) and
+     * prevents a token from expiring mid-request after we hand it out.
+     *
+     * Assumes the access-token TTL is much larger than the buffer. With
+     * TTLs ≤ `expiryBufferMs`, every call will trigger a refresh.
+     */
+    expiryBufferMs?: number;
+    /**
+     * Override for the token store. Defaults to a fresh
+     * `KeyringTokenStore()` (single keychain entry per machine).
+     */
+    tokenStore?: TokenStore;
+    /**
+     * Pre-loaded result of `tokenStore.load()`. When provided, the
+     * function skips its own keychain read and uses this value
+     * instead — lets a caller that already loaded the entry (the CLI
+     * dispatcher does, to derive `parseCommonArgs` defaults) avoid a
+     * redundant second read on the hot path. The same `tokenStore` is
+     * still used for the post-refresh `save()` and the
+     * `invalid_grant` `clear()`.
+     */
+    loadedEntry?: LoadResult;
+    /** Aborts discovery + the refresh POST when fired. */
+    signal?: AbortSignal;
+    /**
+     * Forwarded to discovery. Loopback issuers are always permitted
+     * over http; this flag is the opt-in for non-loopback http.
+     */
+    allowInsecureIssuer?: boolean;
+    /**
+     * Called for soft warnings that are not errors but warrant user
+     * attention (e.g. a fresh `TokenSet` could not be written to the
+     * keychain, stranding the rotated refresh token — see the hazard
+     * note in the body of `getValidAccessToken`). The default prints
+     * to stderr only when stderr is a TTY. Pass a custom handler to
+     * route warnings through your own UI, or `() => {}` to suppress.
+     */
+    onWarning?: (message: string) => void;
+    /** Source of `now`. Defaults to `Date.now`. Injected for test determinism. */
+    now?: () => number;
+}
+/**
+ * Returns a currently-valid access token string for the given issuer,
+ * refreshing via the stored refresh token if the cached access token
+ * is within `expiryBufferMs` of expiring (or already expired).
+ *
+ * Throws `OAuthFlowError("NOT_AUTHENTICATED", ...)` when the user
+ * must re-run `axe-auth login` — covers an empty / corrupt /
+ * version-mismatched store, an expired access token with no refresh
+ * token to rotate with, and a refresh attempt rejected with
+ * `invalid_grant` (which also clears the stored tokens).
+ *
+ * Throws `OAuthFlowError("TOKEN_EXCHANGE_FAILED", ...)` for transient
+ * failures during refresh (network errors, 5xx, malformed responses)
+ * and leaves the stored tokens intact so a retry is possible.
+ *
+ * Throws `OAuthFlowError("DISCOVERY_FAILED", ...)` when the issuer
+ * URL cannot be reached or parsed at refresh time.
+ *
+ * **Concurrency note.** Not safe against parallel invocations for
+ * the same issuer. Keycloak rotates refresh tokens by default; if
+ * two parallel calls both land on the refresh path, only one
+ * winner's rotated refresh token will be persisted and the loser's
+ * rotated token is stranded. The intended consumer is the
+ * `axe-auth token` CLI (a one-shot), so this is fine in context;
+ * per-request callers should wrap in an in-flight-Promise singleton
+ * keyed by issuer.
+ */
+export declare function getValidAccessToken(options: GetValidAccessTokenOptions): Promise<string>;

package/dist/oauth/getValidAccessToken.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getValidAccessToken = getValidAccessToken;
+const discoverOIDC_1 = require("./discoverOIDC");
+const errors_1 = require("./errors");
+const refreshTokens_1 = require("./refreshTokens");
+const tokenStore_1 = require("./tokenStore");
+const DEFAULT_EXPIRY_BUFFER_MS = 60_000;
+function defaultOnWarning(message) {
+    if (process.stderr.isTTY) {
+        console.error(`axe-auth: ${message}`);
+    }
+}
+function isInvalidGrant(err) {
+    return (err instanceof errors_1.OAuthFlowError &&
+        err.code === "TOKEN_EXCHANGE_FAILED" &&
+        err.details?.error === "invalid_grant");
+}
+function notAuthenticated(message, cause) {
+    return new errors_1.OAuthFlowError("NOT_AUTHENTICATED", message, cause === undefined ? undefined : { cause });
+}
+/**
+ * Returns a currently-valid access token string for the given issuer,
+ * refreshing via the stored refresh token if the cached access token
+ * is within `expiryBufferMs` of expiring (or already expired).
+ *
+ * Throws `OAuthFlowError("NOT_AUTHENTICATED", ...)` when the user
+ * must re-run `axe-auth login` — covers an empty / corrupt /
+ * version-mismatched store, an expired access token with no refresh
+ * token to rotate with, and a refresh attempt rejected with
+ * `invalid_grant` (which also clears the stored tokens).
+ *
+ * Throws `OAuthFlowError("TOKEN_EXCHANGE_FAILED", ...)` for transient
+ * failures during refresh (network errors, 5xx, malformed responses)
+ * and leaves the stored tokens intact so a retry is possible.
+ *
+ * Throws `OAuthFlowError("DISCOVERY_FAILED", ...)` when the issuer
+ * URL cannot be reached or parsed at refresh time.
+ *
+ * **Concurrency note.** Not safe against parallel invocations for
+ * the same issuer. Keycloak rotates refresh tokens by default; if
+ * two parallel calls both land on the refresh path, only one
+ * winner's rotated refresh token will be persisted and the loser's
+ * rotated token is stranded. The intended consumer is the
+ * `axe-auth token` CLI (a one-shot), so this is fine in context;
+ * per-request callers should wrap in an in-flight-Promise singleton
+ * keyed by issuer.
+ */
+async function getValidAccessToken(options) {
+    const { issuerURL, clientId, expiryBufferMs = DEFAULT_EXPIRY_BUFFER_MS, tokenStore = new tokenStore_1.KeyringTokenStore(), loadedEntry, signal, allowInsecureIssuer, onWarning = defaultOnWarning, now = Date.now, } = options;
+    const loaded = loadedEntry ?? (await tokenStore.load());
+    if (!loaded.ok) {
+        switch (loaded.reason) {
+            case "empty":
+                throw notAuthenticated("No stored credentials. Run `axe-auth login` first.");
+            case "corrupt":
+                throw notAuthenticated("Stored credentials are unreadable. Run `axe-auth login` to re-authenticate.");
+            case "version-mismatch":
+                throw notAuthenticated(`Stored credentials are from an unsupported schema version (v:${loaded.storedVersion}). Run \`axe-auth login\` to re-authenticate.`);
+        }
+    }
+    // Guard against a mismatch between the requested issuer/client and
+    // the stored entry's. Under single-entry storage, the keychain
+    // holds one set of tokens minted against one (issuer, client)
+    // pair. Refreshing those tokens against a different
+    // discovery/token endpoint would land an unrelated refresh token
+    // at the wrong server and leak it. Refuse rather than silently
+    // proceed so direct library callers (the CLI's verbs warn + route
+    // before getting here) get a clear signal.
+    if (loaded.entry.issuerURL !== issuerURL ||
+        loaded.entry.clientId !== clientId) {
+        throw notAuthenticated(`Stored credentials are for issuer ${loaded.entry.issuerURL} (client ${loaded.entry.clientId}), but the requested issuer is ${issuerURL} (client ${clientId}). Run \`axe-auth login\` to re-authenticate.`);
+    }
+    const tokens = loaded.entry.tokens;
+    if (now() + expiryBufferMs < tokens.expiresAt) {
+        // Still fresh — no network call, no store write.
+        return tokens.accessToken;
+    }
+    if (!tokens.refreshToken) {
+        throw notAuthenticated("Access token has expired and no refresh token is available. Run `axe-auth login` to re-authenticate.");
+    }
+    const config = await (0, discoverOIDC_1.discoverOIDC)(issuerURL, {
+        signal,
+        allowInsecureIssuer,
+    });
+    let fresh;
+    try {
+        fresh = await (0, refreshTokens_1.refreshTokens)({
+            tokenEndpoint: config.tokenEndpoint,
+            clientId,
+            refreshToken: tokens.refreshToken,
+            now,
+            signal,
+        });
+    }
+    catch (err) {
+        if (isInvalidGrant(err)) {
+            // Refresh token revoked / expired server-side. Best-effort
+            // clear of the stored tokens so the next run starts clean —
+            // but if the clear itself fails (e.g. KEYRING_UNAVAILABLE),
+            // prefer surfacing NOT_AUTHENTICATED so the user still gets
+            // the actionable "please run login" signal. Note the clear
+            // failure via onWarning; the next run will see the stale
+            // tokens, try to refresh, and land back here.
+            try {
+                await tokenStore.clear();
+            }
+            catch (clearErr) {
+                onWarning(`Failed to clear stored tokens after refresh rejection: ${clearErr instanceof Error ? clearErr.message : String(clearErr)}. Next run may need to clear manually.`);
+            }
+            throw notAuthenticated("Your session has expired. Run `axe-auth login` to re-authenticate.", err);
+        }
+        // Transient failure — leave the store alone so the user can
+        // retry without re-logging-in.
+        throw err;
+    }
+    // HAZARD: Keycloak (and most rotating-refresh-token providers) have
+    // already consumed the old refresh token server-side by the time
+    // `refreshTokens` returns. If persisting the rotated set fails
+    // here, we hold a valid access token in memory but the stored
+    // refresh token is now stale — the next invocation will POST it,
+    // get `invalid_grant`, and prompt re-authentication.
+    //
+    // We still return the fresh access token so the current call is
+    // useful, and warn the caller so "why does the next run need me to
+    // log in again?" has a breadcrumb.
+    try {
+        await tokenStore.save({
+            tokens: fresh,
+            issuerURL: loaded.entry.issuerURL,
+            clientId: loaded.entry.clientId,
+            allowInsecureIssuer: loaded.entry.allowInsecureIssuer,
+        });
+    }
+    catch (err) {
+        onWarning(`Refreshed tokens could not be saved: ${err instanceof Error ? err.message : String(err)}. The current call will succeed, but the next invocation will require re-authentication.`);
+    }
+    return fresh.accessToken;
+}

package/dist/oauth/index.d.ts

@@ -4,8 +4,13 @@ export { OAuthCallbackError, OAuthFlowError } from "./errors";
 export type { OAuthCallbackErrorCode, OAuthCallbackErrorOptions, OAuthFlowErrorCode, OAuthFlowErrorOptions, } from "./errors";
 export { authorize } from "./authorize";
 export type { AuthorizeOptions } from "./authorize";
-export type { TokenSet } from "./tokenExchange";
+export { getValidAccessToken } from "./getValidAccessToken";
+export type { GetValidAccessTokenOptions } from "./getValidAccessToken";
+export { refreshTokens } from "./refreshTokens";
+export type { RefreshTokensOptions } from "./refreshTokens";
+export type { TokenSet } from "./tokenResponse";
 export { KeyringTokenStore, STORED_BLOB_VERSION } from "./tokenStore";
-export type { TokenStore, LoadResult, KeyringEntry, KeyringEntryFactory, } from "./tokenStore";
+export type { LoadResult, StoredEntry, TokenStore } from "./tokenStore";
+export type { KeyringEntry, KeyringEntryFactory } from "./keyringBinding";
 export { discoverOIDC } from "./discoverOIDC";
 export type { OIDCConfiguration, DiscoverOIDCOptions } from "./discoverOIDC";

package/dist/oauth/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.discoverOIDC = exports.STORED_BLOB_VERSION = exports.KeyringTokenStore = exports.authorize = exports.OAuthFlowError = exports.OAuthCallbackError = exports.startCallbackServer = void 0;
+exports.discoverOIDC = exports.STORED_BLOB_VERSION = exports.KeyringTokenStore = exports.refreshTokens = exports.getValidAccessToken = exports.authorize = exports.OAuthFlowError = exports.OAuthCallbackError = exports.startCallbackServer = void 0;
 var callbackServer_1 = require("./callbackServer");
 Object.defineProperty(exports, "startCallbackServer", { enumerable: true, get: function () { return callbackServer_1.startCallbackServer; } });
 var errors_1 = require("./errors");
@@ -8,6 +8,10 @@ Object.defineProperty(exports, "OAuthCallbackError", { enumerable: true, get: fu
 Object.defineProperty(exports, "OAuthFlowError", { enumerable: true, get: function () { return errors_1.OAuthFlowError; } });
 var authorize_1 = require("./authorize");
 Object.defineProperty(exports, "authorize", { enumerable: true, get: function () { return authorize_1.authorize; } });
+var getValidAccessToken_1 = require("./getValidAccessToken");
+Object.defineProperty(exports, "getValidAccessToken", { enumerable: true, get: function () { return getValidAccessToken_1.getValidAccessToken; } });
+var refreshTokens_1 = require("./refreshTokens");
+Object.defineProperty(exports, "refreshTokens", { enumerable: true, get: function () { return refreshTokens_1.refreshTokens; } });
 var tokenStore_1 = require("./tokenStore");
 Object.defineProperty(exports, "KeyringTokenStore", { enumerable: true, get: function () { return tokenStore_1.KeyringTokenStore; } });
 Object.defineProperty(exports, "STORED_BLOB_VERSION", { enumerable: true, get: function () { return tokenStore_1.STORED_BLOB_VERSION; } });

package/dist/oauth/keyringBinding.d.ts

@@ -0,0 +1,22 @@
+/** Minimal keyring-entry surface consumed by the package's stores. */
+export interface KeyringEntry {
+    /** Writes the password for this entry. */
+    setPassword(password: string): void;
+    /** Reads the current password, or returns `null` if none is set. */
+    getPassword(): string | null;
+    /** Deletes the password and returns `true` if one existed. */
+    deletePassword(): boolean;
+}
+/**
+ * Factory for `KeyringEntry` values. Injection seam for tests;
+ * production callers use the default that constructs
+ * `@napi-rs/keyring` entries lazily.
+ */
+export type KeyringEntryFactory = (service: string, account: string) => KeyringEntry;
+/**
+ * Default `KeyringEntryFactory`. Resolves `@napi-rs/keyring` lazily
+ * so platforms without a prebuilt binding only see a
+ * `KEYRING_UNAVAILABLE` on first store construction, not on module
+ * import.
+ */
+export declare const defaultEntryFactory: KeyringEntryFactory;

package/dist/oauth/keyringBinding.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultEntryFactory = void 0;
+const node_module_1 = require("node:module");
+const errors_1 = require("./errors");
+const requireFromHere = (0, node_module_1.createRequire)(__filename);
+// Lazy-resolved Entry constructor. Importing @napi-rs/keyring at the
+// top of this module would run its native binding loader at
+// module-load time, throwing before any of our OAuthFlowError code
+// catches it and preventing the module from being imported at all on
+// platforms without a prebuilt. We defer the require into
+// `defaultEntryFactory`, which turns that import-time failure into a
+// `KEYRING_UNAVAILABLE` surfaced on the first store construction —
+// not on first save/load/clear, since callers construct stores
+// eagerly as default-arg expressions. Runtime keychain errors
+// (missing D-Bus Secret Service, macOS Keychain denial, etc.) are a
+// separate concern and surface later, inside save/load/clear.
+let cachedEntryCtor = null;
+function resolveEntryCtor() {
+    if (cachedEntryCtor)
+        return cachedEntryCtor;
+    try {
+        const mod = requireFromHere("@napi-rs/keyring");
+        cachedEntryCtor = mod.Entry;
+        return cachedEntryCtor;
+    }
+    catch (cause) {
+        throw new errors_1.OAuthFlowError("KEYRING_UNAVAILABLE", `Could not load @napi-rs/keyring. A prebuilt native binding for this platform may be missing.`, { cause });
+    }
+}
+/**
+ * Default `KeyringEntryFactory`. Resolves `@napi-rs/keyring` lazily
+ * so platforms without a prebuilt binding only see a
+ * `KEYRING_UNAVAILABLE` on first store construction, not on module
+ * import.
+ */
+const defaultEntryFactory = (service, account) => {
+    const Ctor = resolveEntryCtor();
+    return new Ctor(service, account);
+};
+exports.defaultEntryFactory = defaultEntryFactory;

package/dist/oauth/predicates.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Narrows `v` to `string` when it is a non-empty string. Useful for
+ * validating JSON fields from authorization-server responses, where
+ * the spec declares a field as "string" but servers occasionally
+ * return `""` / `null` / missing.
+ */
+export declare function isNonEmptyString(v: unknown): v is string;

package/dist/oauth/predicates.js

@@ -0,0 +1,15 @@
+"use strict";
+// Type-guard predicates shared across the oauth modules. Keep this
+// narrow: anything more substantial than a one-liner probably
+// belongs in its own module rather than piling in here.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isNonEmptyString = isNonEmptyString;
+/**
+ * Narrows `v` to `string` when it is a non-empty string. Useful for
+ * validating JSON fields from authorization-server responses, where
+ * the spec declares a field as "string" but servers occasionally
+ * return `""` / `null` / missing.
+ */
+function isNonEmptyString(v) {
+    return typeof v === "string" && v.length > 0;
+}