@doist/cli-core 0.18.0 → 0.20.0

package/dist/auth/providers/oauth.js

@@ -0,0 +1,145 @@
+import { CliError, getErrorMessage } from '../../errors.js';
+/**
+ * Build a `CliError` with user-supplied `errorHints` prepended and an optional
+ * server-derived `extra` detail appended. Centralises the "user-actionable
+ * first, diagnostic second" ordering used everywhere in this directory.
+ */
+export function buildAuthError(code, message, userHints, extra) {
+    const hints = [...(userHints ?? []), ...(extra ? [extra] : [])];
+    return new CliError(code, message, hints.length > 0 ? { hints } : {});
+}
+/**
+ * Resolve a literal-or-function endpoint/clientId against the current handshake
+ * and runtime flags. Used by every provider in this directory.
+ */
+export async function resolve(resolver, handshake, flags) {
+    return typeof resolver === 'function' ? resolver({ handshake, flags }) : resolver;
+}
+/** Read a response body without letting a stream error escape — used for hints. */
+export async function safeReadText(response) {
+    try {
+        const text = (await response.text()).trim();
+        return text.length > 0 ? text : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Construct the standard PKCE S256 authorize URL. */
+export function buildPkceAuthorizeUrl(input) {
+    const url = new URL(input.authorizeUrl);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('client_id', input.clientId);
+    url.searchParams.set('redirect_uri', input.redirectUri);
+    url.searchParams.set('state', input.state);
+    url.searchParams.set('code_challenge', input.codeChallenge);
+    url.searchParams.set('code_challenge_method', 'S256');
+    if (input.scopes.length > 0) {
+        url.searchParams.set('scope', input.scopes.join(input.scopeSeparator));
+    }
+    return url.toString();
+}
+/**
+ * POST a request, parse a JSON response, and wrap every failure mode as a
+ * typed `CliError`. Common backbone for the OAuth token endpoint and the
+ * RFC 7591 dynamic-client-registration endpoint — both POST a body, both
+ * expect a JSON reply, both want uniform error handling.
+ *
+ * Throws `errorCode` with the configured hints on:
+ *   - network failure (fetch rejection)
+ *   - non-2xx response (body text appended as a hint after `errorHints`)
+ *   - non-JSON 2xx body (a misconfigured proxy returning HTML, etc.)
+ *
+ * Success-shape validation (e.g. `access_token` present) is the caller's
+ * job, because it differs per endpoint.
+ */
+export async function postAndParseJson(input) {
+    const fail = (message, extra) => buildAuthError(input.errorCode, message, input.errorHints, extra);
+    let response;
+    try {
+        response = await input.fetchImpl(input.url, {
+            method: 'POST',
+            headers: input.headers,
+            body: input.body,
+        });
+    }
+    catch (error) {
+        throw fail(`${input.errorLabel} request failed: ${getErrorMessage(error)}`);
+    }
+    if (!response.ok) {
+        const detail = await safeReadText(response);
+        throw fail(`${input.errorLabel} returned HTTP ${response.status}.`, detail);
+    }
+    // Parse defensively — a misconfigured proxy can return a 2xx HTML error
+    // page that would otherwise blow up with a raw SyntaxError.
+    try {
+        return (await response.json());
+    }
+    catch (error) {
+        throw fail(`${input.errorLabel} returned non-JSON response: ${getErrorMessage(error)}`);
+    }
+}
+/**
+ * POST to an OAuth 2.0 token endpoint and parse the standard JSON response.
+ * Covers the public-client `authorization_code` exchange (PKCE) — the caller
+ * owns `grant_type` and the grant-specific params via `body`.
+ *
+ * Failures uniformly throw `CliError('AUTH_TOKEN_EXCHANGE_FAILED', …)`:
+ * network errors, non-2xx responses (with body text as a hint), non-JSON
+ * bodies, and responses missing `access_token`.
+ */
+export async function postTokenEndpoint(input) {
+    const headers = {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        Accept: 'application/json',
+    };
+    const payload = await postAndParseJson({
+        url: input.url,
+        headers,
+        body: input.body.toString(),
+        errorCode: 'AUTH_TOKEN_EXCHANGE_FAILED',
+        errorLabel: 'Token endpoint',
+        errorHints: input.errorHints,
+        fetchImpl: input.fetchImpl,
+    });
+    if (!payload.access_token) {
+        throw buildAuthError('AUTH_TOKEN_EXCHANGE_FAILED', 'Token endpoint response missing access_token.', input.errorHints);
+    }
+    return {
+        accessToken: payload.access_token,
+        refreshToken: payload.refresh_token,
+        expiresAt: expiresAtFromExpiresIn(payload.expires_in),
+    };
+}
+/** Convert an OAuth `expires_in` (seconds from now) into a Unix-epoch ms deadline. */
+export function expiresAtFromExpiresIn(expiresIn) {
+    return typeof expiresIn === 'number' ? Date.now() + expiresIn * 1000 : undefined;
+}
+// Optional peer dep — only DCR and refresh consumers install it. The dynamic
+// import (and a missing-peer failure) is memoised so it isn't repeated on every
+// call that sits on the authenticated-call path.
+let oauthModulePromise;
+/**
+ * Lazily import `oauth4webapi`, surfacing a typed `CliError` when the optional
+ * peer dep is absent (vs. installed-but-broken). Shared by `createPkceProvider`
+ * (refresh) and `createDcrProvider` (registration + token exchange). Caller
+ * `userHints` are prepended on both failure branches so the provider's
+ * `errorHints` contract holds even when the dep is missing.
+ */
+export async function loadOauth4webapi(options) {
+    oauthModulePromise ??= import('oauth4webapi');
+    try {
+        return await oauthModulePromise;
+    }
+    catch (error) {
+        const moduleCode = error?.code;
+        if (moduleCode === 'ERR_MODULE_NOT_FOUND' || moduleCode === 'MODULE_NOT_FOUND') {
+            const hints = [...(options.userHints ?? []), ...(options.missingHints ?? [])];
+            throw new CliError(options.code, options.missingMessage, hints.length > 0 ? { hints } : {});
+        }
+        // Installed but failed to initialise — surface the real cause rather
+        // than a misleading "install it" hint.
+        throw buildAuthError(options.code, `Failed to load oauth4webapi: ${getErrorMessage(error)}`, options.userHints);
+    }
+}
+//# sourceMappingURL=oauth.js.map

package/dist/auth/providers/oauth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.js","sourceRoot":"","sources":["../../../src/auth/providers/oauth.ts"],"names":[],"mappings":"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"}

package/dist/auth/providers/pkce.d.ts

@@ -1,13 +1,17 @@
 import type { AuthAccount, AuthProvider, ValidateInput } from '../types.js';
 /**
  * Lazy resolver: a literal string, or a function that builds one from the
- * current PKCE handshake (so callers can derive the URL or client_id from
- * the active session's `baseUrl` / per-flow flags).
+ * current OAuth handshake (so callers can derive the URL or client_id from
+ * the active session's `baseUrl` / per-flow flags). Used by both
+ * `createPkceProvider` and `createDcrProvider`; prefer the grant-agnostic
+ * alias `OAuthLazyString` for new code.
  */
 export type PkceLazyString = string | ((ctx: {
     handshake: Record<string, unknown>;
     flags: Record<string, unknown>;
-}) => string);
+}) => string | Promise<string>);
+/** Grant-agnostic alias for {@link PkceLazyString}. Identical type. */
+export type OAuthLazyString = PkceLazyString;
 export type PkceProviderOptions<TAccount extends AuthAccount = AuthAccount> = {
     /** OAuth 2.0 authorize endpoint. Function form supports per-flow base URLs (Outline self-hosted). */
     authorizeUrl: PkceLazyString;
@@ -22,6 +26,13 @@ export type PkceProviderOptions<TAccount extends AuthAccount = AuthAccount> = {
     verifierLength?: number;
     /** Probe an authenticated endpoint to confirm the token works and resolve the account. */
     validate: (input: ValidateInput) => Promise<TAccount>;
+    /**
+     * User-facing remediation hints attached to every CliError this factory
+     * throws (token-endpoint failures, internal handshake-state guards).
+     * Server-returned response bodies are appended after these so the
+     * actionable hint stays first.
+     */
+    errorHints?: string[];
     /** Inject a fetch implementation (tests). */
     fetchImpl?: typeof fetch;
 };
@@ -35,8 +46,8 @@ export type PkceProviderOptions<TAccount extends AuthAccount = AuthAccount> = {
  * `runOAuthFlow` and arrives on `AuthorizeInput.scopes`; this factory does
  * not own scope resolution.
  *
- * Flows that need DCR or HTTP Basic auth on the token endpoint implement
- * the `AuthProvider` interface directly.
+ * Flows that need DCR or HTTP Basic auth on the token endpoint use
+ * `createDcrProvider` (or implement the `AuthProvider` interface directly).
  */
 export declare function createPkceProvider<TAccount extends AuthAccount>(options: PkceProviderOptions<TAccount>): AuthProvider<TAccount>;
 //# sourceMappingURL=pkce.d.ts.map

package/dist/auth/providers/pkce.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pkce.d.ts","sourceRoot":"","sources":["../../../src/auth/providers/pkce.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACR,WAAW,EACX,YAAY,EAKZ,aAAa,EAChB,MAAM,aAAa,CAAA;AAEpB;;;;GAIG;AACH,MAAM,MAAM,cAAc,GACpB,MAAM,GACN,CAAC,CAAC,GAAG,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,KAAK,MAAM,CAAC,CAAA;AAE/F,MAAM,MAAM,mBAAmB,CAAC,QAAQ,SAAS,WAAW,GAAG,WAAW,IAAI;IAC1E,qGAAqG;IACrG,YAAY,EAAE,cAAc,CAAA;IAC5B,2EAA2E;IAC3E,QAAQ,EAAE,cAAc,CAAA;IACxB,mFAAmF;IACnF,QAAQ,EAAE,cAAc,CAAA;IACxB,iGAAiG;IACjG,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,kBAAkB;IAClB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,0FAA0F;IAC1F,QAAQ,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;IACrD,6CAA6C;IAC7C,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CAC3B,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,SAAS,WAAW,EAC3D,OAAO,EAAE,mBAAmB,CAAC,QAAQ,CAAC,GACvC,YAAY,CAAC,QAAQ,CAAC,CA6GxB"}
+{"version":3,"file":"pkce.d.ts","sourceRoot":"","sources":["../../../src/auth/providers/pkce.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACR,WAAW,EACX,YAAY,EAMZ,aAAa,EAChB,MAAM,aAAa,CAAA;AAepB;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GACpB,MAAM,GACN,CAAC,CAAC,GAAG,EAAE;IACH,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAClC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACjC,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAA;AAErC,uEAAuE;AACvE,MAAM,MAAM,eAAe,GAAG,cAAc,CAAA;AAE5C,MAAM,MAAM,mBAAmB,CAAC,QAAQ,SAAS,WAAW,GAAG,WAAW,IAAI;IAC1E,qGAAqG;IACrG,YAAY,EAAE,cAAc,CAAA;IAC5B,2EAA2E;IAC3E,QAAQ,EAAE,cAAc,CAAA;IACxB,mFAAmF;IACnF,QAAQ,EAAE,cAAc,CAAA;IACxB,iGAAiG;IACjG,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,kBAAkB;IAClB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,0FAA0F;IAC1F,QAAQ,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;IACrD;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IACrB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CAC3B,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,SAAS,WAAW,EAC3D,OAAO,EAAE,mBAAmB,CAAC,QAAQ,CAAC,GACvC,YAAY,CAAC,QAAQ,CAAC,CAqJxB"}

package/dist/auth/providers/pkce.js

@@ -1,5 +1,10 @@
 import { CliError, getErrorMessage } from '../../errors.js';
 import { deriveChallenge, generateVerifier } from '../pkce.js';
+import { buildAuthError, buildPkceAuthorizeUrl, expiresAtFromExpiresIn, loadOauth4webapi, postTokenEndpoint, resolve, } from './oauth.js';
+// Upper bound on the refresh-token POST. Kept under the refresh helper's
+// stale-lock threshold so a timed-out grant releases the lock before another
+// invocation would consider it abandoned.
+const REFRESH_TIMEOUT_MS = 10_000;
 /**
  * Build an `AuthProvider` for the standard "PKCE S256, public client (no
  * client_secret)" flow. Covers Outline (user-supplied client_id + base_url)
@@ -10,8 +15,8 @@ import { deriveChallenge, generateVerifier } from '../pkce.js';
  * `runOAuthFlow` and arrives on `AuthorizeInput.scopes`; this factory does
  * not own scope resolution.
  *
- * Flows that need DCR or HTTP Basic auth on the token endpoint implement
- * the `AuthProvider` interface directly.
+ * Flows that need DCR or HTTP Basic auth on the token endpoint use
+ * `createDcrProvider` (or implement the `AuthProvider` interface directly).
  */
 export function createPkceProvider(options) {
     const fetchImpl = options.fetchImpl ?? fetch;
@@ -23,20 +28,22 @@ export function createPkceProvider(options) {
                 length: options.verifierLength,
             });
             const challenge = deriveChallenge(verifier);
-            const clientId = resolve(options.clientId, input.handshake, input.flags);
-            const authorizeUrl = resolve(options.authorizeUrl, input.handshake, input.flags);
-            const url = new URL(authorizeUrl);
-            url.searchParams.set('response_type', 'code');
-            url.searchParams.set('client_id', clientId);
-            url.searchParams.set('redirect_uri', input.redirectUri);
-            url.searchParams.set('state', input.state);
-            url.searchParams.set('code_challenge', challenge);
-            url.searchParams.set('code_challenge_method', 'S256');
-            if (input.scopes.length > 0) {
-                url.searchParams.set('scope', input.scopes.join(scopeSeparator));
-            }
+            // Resolve concurrently — both may be async (config read / prompt).
+            const [clientId, authorizeBaseUrl] = await Promise.all([
+                resolve(options.clientId, input.handshake, input.flags),
+                resolve(options.authorizeUrl, input.handshake, input.flags),
+            ]);
+            const authorizeUrl = buildPkceAuthorizeUrl({
+                authorizeUrl: authorizeBaseUrl,
+                clientId,
+                redirectUri: input.redirectUri,
+                state: input.state,
+                scopes: input.scopes,
+                scopeSeparator,
+                codeChallenge: challenge,
+            });
             return {
-                authorizeUrl: url.toString(),
+                authorizeUrl,
                 handshake: { ...input.handshake, codeVerifier: verifier, clientId },
             };
         },
@@ -44,13 +51,13 @@ export function createPkceProvider(options) {
             const verifier = input.handshake.codeVerifier;
             const clientId = input.handshake.clientId;
             if (typeof verifier !== 'string' || typeof clientId !== 'string') {
-                throw new CliError('AUTH_TOKEN_EXCHANGE_FAILED', 'Internal: PKCE handshake state lost between authorize and exchange.');
+                throw buildAuthError('AUTH_TOKEN_EXCHANGE_FAILED', 'Internal: PKCE handshake state lost between authorize and exchange.', options.errorHints);
             }
             // `runOAuthFlow` folds the runtime `flags` into the handshake
             // before calling exchange, so a `tokenUrl: ({ flags }) => ...`
             // resolver sees the same flags it saw during authorize.
             const flags = input.handshake.flags ?? {};
-            const tokenUrl = resolve(options.tokenUrl, input.handshake, flags);
+            const tokenUrl = await resolve(options.tokenUrl, input.handshake, flags);
             const body = new URLSearchParams({
                 grant_type: 'authorization_code',
                 code: input.code,
@@ -58,57 +65,79 @@ export function createPkceProvider(options) {
                 client_id: clientId,
                 code_verifier: verifier,
             });
-            let response;
-            try {
-                response = await fetchImpl(tokenUrl, {
-                    method: 'POST',
-                    headers: {
-                        'Content-Type': 'application/x-www-form-urlencoded',
-                        Accept: 'application/json',
-                    },
-                    body: body.toString(),
-                });
-            }
-            catch (error) {
-                throw new CliError('AUTH_TOKEN_EXCHANGE_FAILED', `Token endpoint request failed: ${getErrorMessage(error)}`);
-            }
-            if (!response.ok) {
-                const detail = await safeReadText(response);
-                throw new CliError('AUTH_TOKEN_EXCHANGE_FAILED', `Token endpoint returned HTTP ${response.status}.`, detail ? { hints: [detail] } : {});
-            }
-            // Parse defensively — a misconfigured proxy can return a 2xx HTML
-            // error page that would otherwise blow up with a raw SyntaxError.
-            let payload;
+            const result = await postTokenEndpoint({
+                url: tokenUrl,
+                body,
+                errorHints: options.errorHints,
+                fetchImpl,
+            });
+            return {
+                accessToken: result.accessToken,
+                refreshToken: result.refreshToken,
+                expiresAt: result.expiresAt,
+            };
+        },
+        validateToken: options.validate,
+        async refreshToken(input) {
+            const oauth = await loadOauth4webapi({
+                code: 'AUTH_REFRESH_UNAVAILABLE',
+                missingMessage: 'oauth4webapi is required for refresh-token support.',
+                missingHints: ['Run `npm install oauth4webapi` in your CLI.'],
+            });
+            // Mirror `exchangeCode`: a resolver that reads `flags` sees the
+            // same view during silent refresh as it did at authorize time.
+            const flags = input.handshake.flags ?? {};
+            const [tokenUrl, clientId] = await Promise.all([
+                resolve(options.tokenUrl, input.handshake, flags),
+                resolve(options.clientId, input.handshake, flags),
+            ]);
+            const as = { issuer: tokenUrl, token_endpoint: tokenUrl };
+            const client = { client_id: clientId, token_endpoint_auth_method: 'none' };
+            // Bound the network call so a hung token endpoint can't block the
+            // CLI indefinitely (and, for refresh consumers, can't hold the
+            // refresh lock forever). Route through the consumer's injected
+            // fetch when present, so a custom transport (proxy dispatcher,
+            // decompression) applies to the refresh grant too — oauth4webapi
+            // otherwise captures the global `fetch`.
+            const requestOptions = {
+                signal: AbortSignal.timeout(REFRESH_TIMEOUT_MS),
+                ...(options.fetchImpl ? { [oauth.customFetch]: options.fetchImpl } : {}),
+            };
             try {
-                payload = (await response.json());
+                const response = await oauth.refreshTokenGrantRequest(as, client, oauth.None(), input.refreshToken, requestOptions);
+                const result = await oauth.processRefreshTokenResponse(as, client, response);
+                return {
+                    accessToken: result.access_token,
+                    refreshToken: result.refresh_token,
+                    expiresAt: expiresAtFromExpiresIn(result.expires_in),
+                };
             }
             catch (error) {
-                throw new CliError('AUTH_TOKEN_EXCHANGE_FAILED', `Token endpoint returned non-JSON response: ${getErrorMessage(error)}`);
-            }
-            if (!payload.access_token) {
-                throw new CliError('AUTH_TOKEN_EXCHANGE_FAILED', 'Token endpoint response missing access_token.');
+                // A ResponseBodyError carries the server's OAuth error JSON.
+                // `invalid_grant` (any status — some proxies remap 400 → 401)
+                // means the refresh token itself was rejected; re-login is the
+                // only recovery. Every other code is transient from cli-core's
+                // POV — but surface the actual `error`/`error_description` so a
+                // misconfigured server (e.g. `invalid_request: Missing
+                // client_secret`) is diagnosable rather than hidden behind
+                // oauth4webapi's generic "server responded with an error".
+                if (error instanceof oauth.ResponseBodyError) {
+                    const detail = error.error_description
+                        ? `${error.error} (${error.error_description})`
+                        : error.error;
+                    if (error.error === 'invalid_grant') {
+                        throw new CliError('AUTH_REFRESH_EXPIRED', `Refresh token rejected: ${detail}`, {
+                            hints: ['Re-run the login command to reauthorize.'],
+                        });
+                    }
+                    throw new CliError('AUTH_REFRESH_TRANSIENT', `Refresh request failed: ${detail}`, {
+                        hints: ['Try again.'],
+                    });
+                }
+                // Network failure, non-JSON body, WWWAuthenticateChallengeError, …
+                throw new CliError('AUTH_REFRESH_TRANSIENT', `Refresh request failed: ${getErrorMessage(error)}`, { hints: ['Try again.'] });
             }
-            return {
-                accessToken: payload.access_token,
-                refreshToken: payload.refresh_token,
-                expiresAt: typeof payload.expires_in === 'number'
-                    ? Date.now() + payload.expires_in * 1000
-                    : undefined,
-            };
         },
-        validateToken: options.validate,
     };
 }
-function resolve(resolver, handshake, flags) {
-    return typeof resolver === 'function' ? resolver({ handshake, flags }) : resolver;
-}
-async function safeReadText(response) {
-    try {
-        const text = (await response.text()).trim();
-        return text.length > 0 ? text : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
 //# sourceMappingURL=pkce.js.map

package/dist/auth/providers/pkce.js.map

@@ -1 +1 @@
-{"version":3,"file":"pkce.js","sourceRoot":"","sources":["../../../src/auth/providers/pkce.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"pkce.js","sourceRoot":"","sources":["../../../src/auth/providers/pkce.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAC3D,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAW9D,OAAO,EACH,cAAc,EACd,qBAAqB,EACrB,sBAAsB,EACtB,gBAAgB,EAChB,iBAAiB,EACjB,OAAO,GACV,MAAM,YAAY,CAAA;AAEnB,yEAAyE;AACzE,6EAA6E;AAC7E,0CAA0C;AAC1C,MAAM,kBAAkB,GAAG,MAAM,CAAA;AA4CjC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAC9B,OAAsC;IAEtC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,KAAK,CAAA;IAC5C,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,GAAG,CAAA;IAEpD,OAAO;QACH,KAAK,CAAC,SAAS,CAAC,KAAqB;YACjC,MAAM,QAAQ,GAAG,gBAAgB,CAAC;gBAC9B,QAAQ,EAAE,OAAO,CAAC,gBAAgB;gBAClC,MAAM,EAAE,OAAO,CAAC,cAAc;aACjC,CAAC,CAAA;YACF,MAAM,SAAS,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAA;YAC3C,mEAAmE;YACnE,MAAM,CAAC,QAAQ,EAAE,gBAAgB,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;gBACnD,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC;gBACvD,OAAO,CAAC,OAAO,CAAC,YAAY,EAAE,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC;aAC9D,CAAC,CAAA;YACF,MAAM,YAAY,GAAG,qBAAqB,CAAC;gBACvC,YAAY,EAAE,gBAAgB;gBAC9B,QAAQ;gBACR,WAAW,EAAE,KAAK,CAAC,WAAW;gBAC9B,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,MAAM,EAAE,KAAK,CAAC,MAAM;gBACpB,cAAc;gBACd,aAAa,EAAE,SAAS;aAC3B,CAAC,CAAA;YAEF,OAAO;gBACH,YAAY;gBACZ,SAAS,EAAE,EAAE,GAAG,KAAK,CAAC,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE;aACtE,CAAA;QACL,CAAC;QAED,KAAK,CAAC,YAAY,CAAC,KAAoB;YACnC,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,CAAC,YAAY,CAAA;YAC7C,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAA;YACzC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;gBAC/D,MAAM,cAAc,CAChB,4BAA4B,EAC5B,qEAAqE,EACrE,OAAO,CAAC,UAAU,CACrB,CAAA;YACL,CAAC;YACD,8DAA8D;YAC9D,+DAA+D;YAC/D,wDAAwD;YACxD,MAAM,KAAK,GAAI,KAAK,CAAC,SAAS,CAAC,KAA6C,IAAI,EAAE,CAAA;YAClF,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,CAAA;YAExE,MAAM,IAAI,GAAG,IAAI,eAAe,CAAC;gBAC7B,UAAU,EAAE,oBAAoB;gBAChC,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,YAAY,EAAE,KAAK,CAAC,WAAW;gBAC/B,SAAS,EAAE,QAAQ;gBACnB,aAAa,EAAE,QAAQ;aAC1B,CAAC,CAAA;YAEF,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC;gBACnC,GAAG,EAAE,QAAQ;gBACb,IAAI;gBACJ,UAAU,EAAE,OAAO,CAAC,UAAU;gBAC9B,SAAS;aACZ,CAAC,CAAA;YACF,OAAO;gBACH,WAAW,EAAE,MAAM,CAAC,WAAW;gBAC/B,YAAY,EAAE,MAAM,CAAC,YAAY;gBACjC,SAAS,EAAE,MAAM,CAAC,SAAS;aAC9B,CAAA;QACL,CAAC;QAED,aAAa,EAAE,OAAO,CAAC,QAAQ;QAE/B,KAAK,CAAC,YAAY,CAAC,KAAmB;YAClC,MAAM,KAAK,GAAG,MAAM,gBAAgB,CAAC;gBACjC,IAAI,EAAE,0BAA0B;gBAChC,cAAc,EAAE,qDAAqD;gBACrE,YAAY,EAAE,CAAC,6CAA6C,CAAC;aAChE,CAAC,CAAA;YACF,gEAAgE;YAChE,+DAA+D;YAC/D,MAAM,KAAK,GAAI,KAAK,CAAC,SAAS,CAAC,KAA6C,IAAI,EAAE,CAAA;YAClF,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;gBAC3C,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC;gBACjD,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC;aACpD,CAAC,CAAA;YACF,MAAM,EAAE,GAAwB,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,QAAQ,EAAE,CAAA;YAC9E,MAAM,MAAM,GAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,0BAA0B,EAAE,MAAM,EAAE,CAAA;YAClF,kEAAkE;YAClE,+DAA+D;YAC/D,+DAA+D;YAC/D,+DAA+D;YAC/D,iEAAiE;YACjE,yCAAyC;YACzC,MAAM,cAAc,GAAgC;gBAChD,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,kBAAkB,CAAC;gBAC/C,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC3E,CAAA;YACD,IAAI,CAAC;gBACD,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,wBAAwB,CACjD,EAAE,EACF,MAAM,EACN,KAAK,CAAC,IAAI,EAAE,EACZ,KAAK,CAAC,YAAY,EAClB,cAAc,CACjB,CAAA;gBACD,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,2BAA2B,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAA;gBAC5E,OAAO;oBACH,WAAW,EAAE,MAAM,CAAC,YAAY;oBAChC,YAAY,EAAE,MAAM,CAAC,aAAa;oBAClC,SAAS,EAAE,sBAAsB,CAAC,MAAM,CAAC,UAAU,CAAC;iBACvD,CAAA;YACL,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACb,6DAA6D;gBAC7D,8DAA8D;gBAC9D,+DAA+D;gBAC/D,+DAA+D;gBAC/D,gEAAgE;gBAChE,uDAAuD;gBACvD,2DAA2D;gBAC3D,2DAA2D;gBAC3D,IAAI,KAAK,YAAY,KAAK,CAAC,iBAAiB,EAAE,CAAC;oBAC3C,MAAM,MAAM,GAAG,KAAK,CAAC,iBAAiB;wBAClC,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,iBAAiB,GAAG;wBAC/C,CAAC,CAAC,KAAK,CAAC,KAAK,CAAA;oBACjB,IAAI,KAAK,CAAC,KAAK,KAAK,eAAe,EAAE,CAAC;wBAClC,MAAM,IAAI,QAAQ,CACd,sBAAsB,EACtB,2BAA2B,MAAM,EAAE,EACnC;4BACI,KAAK,EAAE,CAAC,0CAA0C,CAAC;yBACtD,CACJ,CAAA;oBACL,CAAC;oBACD,MAAM,IAAI,QAAQ,CACd,wBAAwB,EACxB,2BAA2B,MAAM,EAAE,EACnC;wBACI,KAAK,EAAE,CAAC,YAAY,CAAC;qBACxB,CACJ,CAAA;gBACL,CAAC;gBACD,mEAAmE;gBACnE,MAAM,IAAI,QAAQ,CACd,wBAAwB,EACxB,2BAA2B,eAAe,CAAC,KAAK,CAAC,EAAE,EACnD,EAAE,KAAK,EAAE,CAAC,YAAY,CAAC,EAAE,CAC5B,CAAA;YACL,CAAC;QACL,CAAC;KACJ,CAAA;AACL,CAAC"}

package/dist/auth/refresh.d.ts

@@ -0,0 +1,49 @@
+import type { AccountRef, AuthAccount, AuthProvider, TokenBundle, TokenStore } from './types.js';
+export type RefreshAccessTokenOptions<TAccount extends AuthAccount> = {
+    store: TokenStore<TAccount>;
+    provider: AuthProvider<TAccount>;
+    ref?: AccountRef;
+    /**
+     * Refresh proactively when the access token's expiry is within this many
+     * ms of now. Default 60_000 (60s). Ignored when `force: true`.
+     */
+    skewMs?: number;
+    /**
+     * Reactive path: caller hit a 401 and wants a rotation regardless of
+     * expiry. Skips the skew check; still honours all the "unavailable"
+     * gates (no refresh token, no provider hook, no `activeBundle`/`setBundle`).
+     */
+    force?: boolean;
+    /**
+     * Path to the O_EXCL concurrency lock file. Required — cli-core does not
+     * interpret `~` or know where the consumer's config lives. Recommended:
+     * `${getConfigPath(serviceName)}.refresh.lock`.
+     */
+    lockPath: string;
+    /**
+     * Forwarded to `provider.refreshToken` as its `handshake`, so consumers
+     * can pass runtime context the provider's resolvers need (e.g. a
+     * `--env`-derived base URL / client id). Defaults to `{}`.
+     */
+    handshake?: Record<string, unknown>;
+};
+export type RefreshAccessTokenResult<TAccount extends AuthAccount> = {
+    rotated: boolean;
+    bundle: TokenBundle;
+    account: TAccount;
+};
+/**
+ * Rotate the access token using the stored refresh token. Proactive when
+ * `accessTokenExpiresAt` is within `skewMs` of now; reactive when `force:
+ * true`. Uses an `O_EXCL` file lock at `lockPath` so concurrent CLI
+ * invocations don't issue parallel refresh-token grants — one POSTs, the
+ * others re-read the rotated bundle from the store.
+ *
+ * Throws `AUTH_REFRESH_UNAVAILABLE` when refresh isn't possible in the
+ * current setup: store doesn't implement `activeBundle` + `setBundle`,
+ * provider doesn't implement `refreshToken`, no credential, or no refresh
+ * token. Server-side rejections surface as `AUTH_REFRESH_EXPIRED` (re-login
+ * required) or `AUTH_REFRESH_TRANSIENT` (retryable).
+ */
+export declare function refreshAccessToken<TAccount extends AuthAccount>(options: RefreshAccessTokenOptions<TAccount>): Promise<RefreshAccessTokenResult<TAccount>>;
+//# sourceMappingURL=refresh.d.ts.map

package/dist/auth/refresh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh.d.ts","sourceRoot":"","sources":["../../src/auth/refresh.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAEhG,MAAM,MAAM,yBAAyB,CAAC,QAAQ,SAAS,WAAW,IAAI;IAClE,KAAK,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAA;IAC3B,QAAQ,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAA;IAChC,GAAG,CAAC,EAAE,UAAU,CAAA;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;IACf;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACtC,CAAA;AAED,MAAM,MAAM,wBAAwB,CAAC,QAAQ,SAAS,WAAW,IAAI;IACjE,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE,WAAW,CAAA;IACnB,OAAO,EAAE,QAAQ,CAAA;CACpB,CAAA;AAUD;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CAAC,QAAQ,SAAS,WAAW,EACjE,OAAO,EAAE,yBAAyB,CAAC,QAAQ,CAAC,GAC7C,OAAO,CAAC,wBAAwB,CAAC,QAAQ,CAAC,CAAC,CA4F7C"}