@tigeropenapi/tigeropen 0.5.5 → 0.5.7

package/dist/esm/auth/oauth2/session-manager.js

@@ -0,0 +1,725 @@
+/**
+ * OAuth 2.0 authorization session management.
+ *
+ * The manager performs metadata discovery, dynamic registration, loopback or device
+ * authorization, token refresh, and persistence. Requested scopes are derived from
+ * `scopes_supported` metadata. Construction performs no network requests.
+ */
+import { createHash, randomBytes } from 'crypto';
+import { OAuth2ClientRegistration } from './client-registration.js';
+import { OAuth2DeviceAuthorization } from './device-authorization.js';
+import { OAuth2Category, OAuth2Error, RejectedGrantError } from './errors.js';
+import * as httpUtils from './http-utils.js';
+import { LoopbackReceiver } from './loopback-receiver.js';
+import { OAuth2Metadata } from './metadata.js';
+import { currentMillis, OAuth2Token } from './token.js';
+import { DEFAULT_SURFACE, OAuth2TokenStore } from './token-store.js';
+export const ENV_ISSUER = 'TIGEROPEN_OAUTH2_ISSUER';
+/**
+ * Production authorization server. The environment variable or constructor argument
+ * overrides this value.
+ */
+export const BUILTIN_ISSUER = 'https://openapi-oauth2.tigerfintech.com';
+/** How early to refresh an access token. */
+export const DEFAULT_REFRESH_AHEAD_MILLIS = 300 * 1000;
+/** Remaining lifetime below which a token is no longer handed out. */
+export const MIN_USABLE_REMAINING_MILLIS = 30 * 1000;
+/** How long to wait for the browser callback. */
+export const DEFAULT_AUTHORIZE_TIMEOUT_SECONDS = 5 * 60;
+/** Added to the polling interval on each `slow_down`. */
+const DEVICE_SLOW_DOWN_INCREMENT_SECONDS = 5;
+/** Fallback when the device authorization response omits `expires_in`. */
+const DEFAULT_DEVICE_EXPIRES_IN_SECONDS = 600;
+/**
+ * Fixed callback port for a manually configured clientId. Chosen to stay clear of the
+ * default Linux ephemeral range (from 32768) and of common dev ports.
+ */
+export const DEFAULT_MANUAL_CALLBACK_PORT = 18888;
+const GRANT_TYPE_AUTHORIZATION_CODE = 'authorization_code';
+const GRANT_TYPE_REFRESH_TOKEN = 'refresh_token';
+const GRANT_TYPE_DEVICE_CODE = 'urn:ietf:params:oauth:grant-type:device_code';
+/**
+ * Application name registered by the SDK itself. Shown on the user's authorization
+ * page, so an entry point that registers its own client passes its own name.
+ */
+export const CLIENT_NAME = 'Tiger TypeScript SDK';
+/** OAuth 2.0 authorization session manager. */
+export class OAuth2SessionManager {
+    constructor(options = {}) {
+        /** In-flight refresh, so concurrent callers share one token request (single-flight). */
+        this.refreshInFlight = null;
+        /** In-flight metadata discovery, so concurrent callers share one round trip. */
+        this.metadataInFlight = null;
+        this._issuer = trimTrailingSlash(options.issuer || OAuth2SessionManager.defaultIssuer());
+        this._callbackPort = options.callbackPort || 0;
+        this.explicitClientId = options.clientId || undefined;
+        this.authorizeTimeoutSeconds = options.authorizeTimeoutSeconds ?? DEFAULT_AUTHORIZE_TIMEOUT_SECONDS;
+        this.clientName = options.clientName || CLIENT_NAME;
+        this.store = options.store ?? new OAuth2TokenStore(options.home, options.surface ?? DEFAULT_SURFACE);
+    }
+    static defaultIssuer() {
+        return trimTrailingSlash(process.env[ENV_ISSUER] || BUILTIN_ISSUER);
+    }
+    get issuer() {
+        return this._issuer;
+    }
+    /** Currently known clientId; undefined before registration in dynamic mode. */
+    get clientId() {
+        return this.knownClientId();
+    }
+    get hasExplicitClientId() {
+        return this.explicitClientId !== undefined;
+    }
+    get callbackPort() {
+        return this._callbackPort;
+    }
+    /** Scopes requested by this session, space-separated. Fetches metadata. */
+    async scopes() {
+        return this.resolveScopes();
+    }
+    /**
+     * Create a default session and perform browser authorization when required.
+     *
+     * The callback receives the authorization URL; the SDK does not open a browser.
+     */
+    static async loginWithDefaults(onAuthorizationUrl) {
+        const sessions = new OAuth2SessionManager();
+        await sessions.loginIfNeeded(onAuthorizationUrl);
+        return sessions;
+    }
+    /** Create a default session and perform device authorization when required. */
+    static async loginWithDeviceCodeDefaults(onDeviceAuthorization) {
+        const sessions = new OAuth2SessionManager();
+        await sessions.loginWithDeviceCodeIfNeeded(onDeviceAuthorization);
+        return sessions;
+    }
+    /**
+     * Perform browser authorization with a loopback redirect and PKCE.
+     *
+     * @param onAuthorizationUrl callback receiving the authorization URL
+     */
+    async login(onAuthorizationUrl) {
+        const metadata = await this.metadataOf();
+        const clientId = await this.resolveClientId();
+        const scopes = await this.resolveScopes();
+        // The receiver must be listening before the authorization request is issued.
+        const receiver = await LoopbackReceiver.start(this.effectiveCallbackPort());
+        const verifier = randomUrlSafe(64);
+        const state = randomUrlSafe(24);
+        let params;
+        try {
+            const url = `${metadata.authorizationEndpoint}?` + query({
+                response_type: 'code',
+                client_id: clientId,
+                redirect_uri: receiver.redirectUri,
+                scope: scopes,
+                state,
+                code_challenge: s256(verifier),
+                code_challenge_method: 'S256',
+            });
+            await onAuthorizationUrl(url);
+            params = await receiver.waitForCallback(this.authorizeTimeoutSeconds);
+        }
+        finally {
+            receiver.close();
+        }
+        const error = params['error'];
+        if (error) {
+            throw new OAuth2Error(OAuth2Category.CallbackFailed, `authorization denied: ${error} ${params['error_description'] ?? ''}`);
+        }
+        if (params['state'] !== state) {
+            // A mismatch indicates that the callback does not belong to the active flow.
+            throw new OAuth2Error(OAuth2Category.CallbackFailed, 'state mismatch in authorization callback');
+        }
+        const code = params['code'];
+        if (!code) {
+            throw new OAuth2Error(OAuth2Category.CallbackFailed, 'authorization callback has no code');
+        }
+        let token;
+        try {
+            token = await this.exchange({
+                grant_type: GRANT_TYPE_AUTHORIZATION_CODE,
+                code,
+                redirect_uri: receiver.redirectUri,
+                client_id: clientId,
+                code_verifier: verifier,
+            }, scopes, clientId);
+        }
+        catch (e) {
+            // A refused authorization code says nothing about the persisted token, so that is
+            // left alone. A refused client registration is removed so it is not reused.
+            if (e instanceof RejectedGrantError) {
+                this.forgetRejectedRegistration(e);
+            }
+            throw e;
+        }
+        this.persist(token);
+        return token;
+    }
+    /**
+     * Use the existing local authorization if usable, otherwise run a full loopback +
+     * PKCE authorization.
+     */
+    async loginIfNeeded(onAuthorizationUrl) {
+        const reusable = await this.reusableToken();
+        return reusable ?? this.login(onAuthorizationUrl);
+    }
+    /**
+     * Reuse local authorization or perform device authorization (RFC 8628).
+     *
+     * Device authorization supports environments without a local browser. Unlike loopback
+     * authorization with PKCE, it has no redirect binding or proof that the initiating and
+     * redeeming clients are the same party, increasing phishing risk. Loopback
+     * authorization is preferred when a local browser is available.
+     */
+    async loginWithDeviceCodeIfNeeded(onDeviceAuthorization) {
+        const reusable = await this.reusableToken();
+        return reusable ?? this.loginWithDeviceCode(onDeviceAuthorization);
+    }
+    /**
+     * Perform device authorization as defined by RFC 8628.
+     *
+     * This flow is intended for environments without a local browser and has the security
+     * limitations documented by {@link loginWithDeviceCodeIfNeeded}.
+     */
+    async loginWithDeviceCode(onDeviceAuthorization) {
+        const metadata = await this.metadataOf();
+        if (!metadata.deviceAuthorizationEndpoint) {
+            throw new OAuth2Error(OAuth2Category.MetadataUnavailable, 'authorization server does not advertise a device_authorization_endpoint');
+        }
+        const clientId = await this.resolveClientId();
+        const scopes = await this.resolveScopes();
+        const device = await this.requestDeviceAuthorization(metadata, clientId, scopes);
+        await onDeviceAuthorization(device);
+        const token = await this.pollForDeviceToken(metadata, device, clientId, scopes);
+        this.persist(token);
+        return token;
+    }
+    /**
+     * Revoke authorization under RFC 7009 and delete the local token.
+     *
+     * Dynamic client registration is retained across logout. The local token is deleted
+     * even if server-side revocation fails.
+     *
+     * @returns true when server-side revocation succeeds; false when only local state is
+     *   cleared and the server credential may remain valid
+     */
+    async logout() {
+        const clientId = this.knownClientId();
+        const revoked = await this.revoke(this.currentToken(), clientId);
+        if (clientId) {
+            this.store.deleteToken(clientId);
+        }
+        this.token = undefined;
+        return revoked;
+    }
+    /**
+     * Return a usable access token, refreshing near expiry.
+     *
+     * Throws `ReauthorizationRequired` when no authorization is available. Browser
+     * authorization is never started implicitly.
+     *
+     * A refresh being due does not make the caller wait for one. While the current token
+     * still has {@link MIN_USABLE_REMAINING_MILLIS} of life, a refresh already running
+     * elsewhere is left to finish and the current token is returned.
+     */
+    async getAccessToken() {
+        const token = this.currentToken();
+        if (!token || !token.accessToken) {
+            throw new OAuth2Error(OAuth2Category.ReauthorizationRequired, 'not authorized yet, call login() first');
+        }
+        if (!token.needsRefresh(DEFAULT_REFRESH_AHEAD_MILLIS)) {
+            return token.accessToken;
+        }
+        if (token.remainingMillis() > MIN_USABLE_REMAINING_MILLIS && this.refreshInFlight !== null) {
+            // Refresh due, token still good, and somebody else already has the exchange.
+            return token.accessToken;
+        }
+        const refreshed = await this.refresh(token.accessToken);
+        return refreshed.accessToken;
+    }
+    /** The current token, or undefined. Sends no requests and triggers no authorization. */
+    status() {
+        return this.currentToken();
+    }
+    /**
+     * Whether asking for a token now would trigger a refresh. Reads memory only.
+     *
+     * Exists so no other component needs a refresh-ahead window of its own.
+     */
+    shouldRefreshSoon() {
+        const token = this.currentToken();
+        return !!token && token.needsRefresh(DEFAULT_REFRESH_AHEAD_MILLIS);
+    }
+    isAuthorized() {
+        return this.currentToken() !== undefined;
+    }
+    /** Refresh because the token is close to expiry. */
+    refresh(failedAccessToken) {
+        return this.doRefresh(failedAccessToken, false);
+    }
+    /**
+     * Refresh after a 401 even when the token is not near expiry.
+     *
+     * @param failedAccessToken token used by the failed request; comparison with the
+     *   current token detects rotation completed elsewhere and preserves single-flight
+     *   refresh behavior
+     */
+    refreshAfterUnauthorized(failedAccessToken) {
+        return this.doRefresh(failedAccessToken, true);
+    }
+    /**
+     * Single-flight refresh: the first caller performs rotation while others await the
+     * same promise.
+     */
+    async doRefresh(failedAccessToken, force) {
+        while (this.refreshInFlight) {
+            // Re-run the guards once the running exchange settles: it may already have
+            // produced exactly the token this caller needs. Its failure belongs to whoever
+            // started it; this caller re-evaluates from the state it left behind.
+            try {
+                await this.refreshInFlight;
+            }
+            catch {
+                // Reported to the caller that owns the exchange.
+            }
+            // Another waiter may have claimed the next exchange while this one resumed, so
+            // the loop re-reads rather than falling straight through.
+        }
+        // No await between the loop exit and the claim below, so exactly one caller claims.
+        return this.refreshOnce(failedAccessToken, force);
+    }
+    refreshOnce(failedAccessToken, force) {
+        const current = this.currentToken();
+        if (!current) {
+            return Promise.reject(new OAuth2Error(OAuth2Category.ReauthorizationRequired, 'not authorized yet, call login() first'));
+        }
+        if (failedAccessToken !== undefined && current.accessToken !== failedAccessToken) {
+            // Already rotated elsewhere. Compares token values rather than timestamps: equal
+            // timestamps do not imply the same token.
+            return Promise.resolve(current);
+        }
+        if (!force && !current.needsRefresh(DEFAULT_REFRESH_AHEAD_MILLIS)) {
+            return Promise.resolve(current);
+        }
+        if (!current.hasRefreshToken()) {
+            return Promise.reject(new OAuth2Error(OAuth2Category.ReauthorizationRequired, 'no refresh_token available, re-authorization required'));
+        }
+        const running = this.exchangeRefreshToken(current)
+            .catch((e) => {
+            if (e instanceof RejectedGrantError) {
+                return this.recoverOrGiveUp(current, e);
+            }
+            throw e;
+        })
+            .finally(() => {
+            if (this.refreshInFlight === running) {
+                this.refreshInFlight = null;
+            }
+        });
+        this.refreshInFlight = running;
+        return running;
+    }
+    /**
+     * Handle a refresh the authorization server rejected.
+     *
+     * Refresh tokens rotate, so the rejected value may already have been replaced by
+     * another process sharing this store. The store is re-read before any local state is
+     * removed, and the authorization is treated as ended only once the newest stored
+     * credential is rejected too.
+     */
+    async recoverOrGiveUp(rejectedToken, rejected) {
+        const stored = this.reloadFromStore(rejectedToken.clientId);
+        const superseded = stored !== null && stored.accessToken !== rejectedToken.accessToken;
+        if (!superseded) {
+            // Nothing newer exists, so the rejection is about the authorization itself.
+            this.forgetRejectedAuthorization(rejected, rejectedToken);
+            throw rejected;
+        }
+        this.token = stored;
+        if (!stored.needsRefresh(DEFAULT_REFRESH_AHEAD_MILLIS)) {
+            // Already refreshed elsewhere, so no second request is needed.
+            return stored;
+        }
+        if (!stored.hasRefreshToken()) {
+            this.forgetRejectedAuthorization(rejected, rejectedToken);
+            throw rejected;
+        }
+        try {
+            return await this.exchangeRefreshToken(stored);
+        }
+        catch (e) {
+            // The credential adopted above was refused too.
+            if (e instanceof RejectedGrantError) {
+                this.forgetRejectedAuthorization(e, stored);
+            }
+            throw e;
+        }
+    }
+    /** Exchange the given token's refresh token for a new access token and persist it. */
+    async exchangeRefreshToken(base) {
+        const clientId = base.clientId || this.knownClientId();
+        const token = await this.exchange({
+            grant_type: GRANT_TYPE_REFRESH_TOKEN,
+            refresh_token: base.refreshToken,
+            client_id: clientId,
+        }, base.scope, clientId);
+        if (!token.refreshToken) {
+            // Preserve the existing refresh token when rotation omits a replacement.
+            token.refreshToken = base.refreshToken;
+        }
+        this.persist(token);
+        return token;
+    }
+    /**
+     * Read the stored token from disk, bypassing the in-memory copy.
+     *
+     * @returns the stored token, or null when there is none or it cannot be read
+     */
+    reloadFromStore(clientId) {
+        if (!clientId)
+            return null;
+        try {
+            return this.store.loadToken(clientId, this._issuer);
+        }
+        catch {
+            // An unreadable store tells us nothing about the grant, so the rejection stands.
+            return null;
+        }
+    }
+    /**
+     * Remove the local token, and the dynamic registration when that was refused.
+     *
+     * Only the credential that was refused is removed, and only while it is still the one
+     * on disk. Another process sharing the store may have replaced it in the meantime, and
+     * that replacement was never refused.
+     */
+    forgetRejectedAuthorization(rejected, rejectedToken) {
+        const clientId = rejectedToken?.clientId;
+        const stored = clientId ? this.reloadFromStore(clientId) : null;
+        if (stored !== null && stored.accessToken !== rejectedToken?.accessToken) {
+            // A newer credential was stored while this one was refused; keep it.
+        }
+        else if (clientId) {
+            this.store.deleteToken(clientId);
+        }
+        // The in-memory copy is the refused one either way. Dropping it makes the next call
+        // read whatever is on disk.
+        this.token = undefined;
+        this.forgetRejectedRegistration(rejected);
+    }
+    /**
+     * Remove a refused dynamic client registration so the next authorization registers a
+     * new one. Explicit clientIds are left alone.
+     */
+    forgetRejectedRegistration(rejected) {
+        if (rejected.isClientRejected && this.explicitClientId === undefined) {
+            this.store.deleteClientRegistration(this._issuer);
+            this.registeredClientId = undefined;
+        }
+    }
+    /**
+     * Return a reusable local token, refreshing it when required.
+     *
+     * @returns undefined when interactive authorization is required
+     */
+    async reusableToken() {
+        const existing = this.currentToken();
+        if (!existing || !existing.accessToken)
+            return undefined;
+        if (!existing.needsRefresh(DEFAULT_REFRESH_AHEAD_MILLIS))
+            return existing;
+        if (existing.hasRefreshToken()) {
+            try {
+                return await this.refresh(existing.accessToken);
+            }
+            catch (e) {
+                // Only terminal authorization errors require interactive authorization;
+                // transient network and server errors remain retryable.
+                if (!(e instanceof OAuth2Error) || e.category !== OAuth2Category.ReauthorizationRequired) {
+                    throw e;
+                }
+            }
+        }
+        return undefined;
+    }
+    currentToken() {
+        if (this.token)
+            return this.token;
+        const clientId = this.knownClientId();
+        if (!clientId)
+            return undefined;
+        const token = this.store.loadToken(clientId, this._issuer);
+        if (token) {
+            this.token = token;
+        }
+        return token ?? undefined;
+    }
+    /**
+     * The known clientId, without triggering registration. Manual mode never reads
+     * `clients/`.
+     */
+    knownClientId() {
+        if (this.explicitClientId)
+            return this.explicitClientId;
+        if (this.registeredClientId)
+            return this.registeredClientId;
+        const clientId = this.store.loadClientId(this._issuer);
+        if (clientId) {
+            this.registeredClientId = clientId;
+        }
+        return clientId ?? undefined;
+    }
+    persist(token) {
+        this.token = token;
+        this.store.saveToken(token);
+    }
+    effectiveCallbackPort() {
+        if (this._callbackPort > 0)
+            return this._callbackPort;
+        // A manual clientId was registered by hand with a concrete redirect_uri the SDK
+        // cannot see, so both sides agree on this port; dynamic registration sends a
+        // portless redirect_uri and can let the system assign one.
+        return this.explicitClientId ? DEFAULT_MANUAL_CALLBACK_PORT : 0;
+    }
+    async resolveScopes() {
+        if (this.resolvedScopes !== undefined)
+            return this.resolvedScopes;
+        const metadata = await this.metadataOf();
+        if (!metadata.scopesSupported.length) {
+            // Missing scope metadata is rejected instead of inferring incomplete scopes.
+            throw new OAuth2Error(OAuth2Category.MetadataUnavailable, 'authorization server metadata has no scopes_supported');
+        }
+        this.resolvedScopes = normalizeScopes(metadata.scopesSupported.join(' '));
+        return this.resolvedScopes;
+    }
+    metadataOf() {
+        if (this.metadata)
+            return Promise.resolve(this.metadata);
+        if (this.metadataInFlight)
+            return this.metadataInFlight;
+        const url = `${this._issuer}/.well-known/oauth-authorization-server`;
+        const running = httpUtils.getJson(url)
+            .then((data) => {
+            const metadata = OAuth2Metadata.fromJSON(data);
+            if (!metadata || !metadata.authorizationEndpoint || !metadata.tokenEndpoint) {
+                throw new OAuth2Error(OAuth2Category.MetadataUnavailable, `incomplete authorization server metadata from ${url}`);
+            }
+            this.metadata = metadata;
+            return metadata;
+        })
+            .finally(() => {
+            if (this.metadataInFlight === running) {
+                this.metadataInFlight = null;
+            }
+        });
+        this.metadataInFlight = running;
+        return running;
+    }
+    /** Manual clientId > saved registration whose scopes still cover > register. */
+    async resolveClientId() {
+        if (this.explicitClientId)
+            return this.explicitClientId;
+        const required = await this.resolveScopes();
+        const registration = this.store.loadClientRegistration(this._issuer);
+        if (registration?.clientId && scopesCover(registration.registeredScopes, required)) {
+            this.registeredClientId = registration.clientId;
+            return registration.clientId;
+        }
+        return this.register(required);
+    }
+    /**
+     * Register a public client under RFC 7591.
+     *
+     * Registration omits scope. The granted scope set is stored separately so a wider
+     * requirement triggers re-registration instead of `invalid_scope`.
+     */
+    async register(scopes) {
+        const metadata = await this.metadataOf();
+        if (!metadata.registrationEndpoint) {
+            throw new OAuth2Error(OAuth2Category.ClientRegistrationRequired, 'authorization server does not support dynamic registration; pass clientId explicitly');
+        }
+        const port = this._callbackPort;
+        const redirectUri = port > 0 ? `http://127.0.0.1:${port}/callback` : 'http://127.0.0.1/callback';
+        const response = await httpUtils.postJson(metadata.registrationEndpoint, {
+            client_name: this.clientName,
+            redirect_uris: [redirectUri],
+            grant_types: [GRANT_TYPE_AUTHORIZATION_CODE, GRANT_TYPE_REFRESH_TOKEN, GRANT_TYPE_DEVICE_CODE],
+            response_types: ['code'],
+            // Public client: there is no client_secret to hide, PKCE is the protection
+            token_endpoint_auth_method: 'none',
+        });
+        const error = response['error'];
+        if (error) {
+            throw new OAuth2Error(OAuth2Category.ClientRegistrationRequired, `dynamic registration failed: ${String(error)} ${String(response['error_description'] ?? '')}`);
+        }
+        const clientId = response['client_id'];
+        if (typeof clientId !== 'string' || !clientId) {
+            throw new OAuth2Error(OAuth2Category.ClientRegistrationRequired, 'dynamic registration response has no client_id');
+        }
+        this.store.saveClientRegistration(new OAuth2ClientRegistration({
+            issuer: this._issuer,
+            clientId,
+            clientName: this.clientName,
+            registeredScopes: normalizeScopes(response['scope']) ?? scopes,
+            clientIdIssuedAt: typeof response['client_id_issued_at'] === 'number'
+                ? response['client_id_issued_at']
+                : Math.floor(currentMillis() / 1000),
+        }));
+        this.registeredClientId = clientId;
+        return clientId;
+    }
+    async requestDeviceAuthorization(metadata, clientId, scopes) {
+        const response = await httpUtils.postForm(metadata.deviceAuthorizationEndpoint, {
+            client_id: clientId,
+            scope: scopes,
+        });
+        const error = response['error'];
+        if (error) {
+            throw new OAuth2Error(OAuth2Category.DeviceAuthorizationFailed, `device authorization failed: ${String(error)} ${String(response['error_description'] ?? '')}`);
+        }
+        const device = OAuth2DeviceAuthorization.fromJSON(response);
+        if (!device || !device.deviceCode || !device.userCode) {
+            throw new OAuth2Error(OAuth2Category.DeviceAuthorizationFailed, 'incomplete device authorization response');
+        }
+        return device;
+    }
+    /** Poll the token endpoint according to RFC 8628 response semantics. */
+    async pollForDeviceToken(metadata, device, clientId, scopes) {
+        let interval = device.effectiveIntervalSeconds();
+        const expiresIn = device.expiresIn || DEFAULT_DEVICE_EXPIRES_IN_SECONDS;
+        const deadline = currentMillis() + expiresIn * 1000;
+        for (;;) {
+            if (currentMillis() >= deadline) {
+                throw new OAuth2Error(OAuth2Category.DeviceAuthorizationFailed, 'device authorization was not approved in time');
+            }
+            await sleep(interval * 1000);
+            const response = await httpUtils.postForm(metadata.tokenEndpoint, {
+                grant_type: GRANT_TYPE_DEVICE_CODE,
+                device_code: device.deviceCode,
+                client_id: clientId,
+            });
+            const error = response['error'];
+            if (!error) {
+                return this.toToken(response, scopes, clientId);
+            }
+            if (error === 'authorization_pending')
+                continue;
+            if (error === 'slow_down') {
+                interval += DEVICE_SLOW_DOWN_INCREMENT_SECONDS;
+                continue;
+            }
+            if (error === 'access_denied') {
+                throw new OAuth2Error(OAuth2Category.DeviceAuthorizationFailed, 'device authorization was denied by the user');
+            }
+            if (error === 'expired_token') {
+                throw new OAuth2Error(OAuth2Category.DeviceAuthorizationFailed, 'device code expired before it was approved');
+            }
+            throw new OAuth2Error(OAuth2Category.TokenRequestFailed, `device token request failed: ${String(error)} ${String(response['error_description'] ?? '')}`);
+        }
+    }
+    async exchange(form, requestedScopes, clientId) {
+        const metadata = await this.metadataOf();
+        const response = await httpUtils.postForm(metadata.tokenEndpoint, form);
+        const error = response['error'];
+        if (error) {
+            const description = String(response['error_description'] ?? '');
+            if (error === 'invalid_grant' || error === 'invalid_client') {
+                // Reported only; removing local state is left to the caller.
+                throw new RejectedGrantError(String(error), description);
+            }
+            throw new OAuth2Error(OAuth2Category.TokenRequestFailed, `token request failed: ${String(error)} ${description}`);
+        }
+        return this.toToken(response, requestedScopes, clientId);
+    }
+    toToken(response, requestedScopes, clientId) {
+        const accessToken = response['access_token'];
+        if (typeof accessToken !== 'string' || !accessToken) {
+            throw new OAuth2Error(OAuth2Category.TokenRequestFailed, 'token response has no access_token');
+        }
+        const expiresIn = typeof response['expires_in'] === 'number' ? response['expires_in'] : 3600;
+        return new OAuth2Token({
+            issuer: this._issuer,
+            clientId,
+            accessToken,
+            refreshToken: typeof response['refresh_token'] === 'string' ? response['refresh_token'] : undefined,
+            tokenType: typeof response['token_type'] === 'string' ? response['token_type'] : 'Bearer',
+            // The response scope wins: what was granted may be narrower than requested
+            scope: normalizeScopes(response['scope']) ?? requestedScopes,
+            expiresAt: currentMillis() + expiresIn * 1000,
+        });
+    }
+    /**
+     * Attempt server-side revocation without throwing.
+     *
+     * The refresh token is preferred because RFC 7009 §2.1 permits revocation of its
+     * associated access tokens. RFC 7009 §2.2 also returns success for unknown or
+     * previously revoked tokens.
+     */
+    async revoke(current, clientId) {
+        if (!current || !clientId)
+            return false;
+        const value = current.refreshToken || current.accessToken;
+        const hint = current.refreshToken ? 'refresh_token' : 'access_token';
+        if (!value)
+            return false;
+        try {
+            const endpoint = (await this.metadataOf()).revocationEndpoint;
+            if (!endpoint) {
+                // Revocation is optional under RFC 8414.
+                return false;
+            }
+            const status = await httpUtils.postFormForStatus(endpoint, {
+                token: value,
+                token_type_hint: hint,
+                client_id: clientId,
+            });
+            // HTTP 400 and 401 indicate that the server rejected the client.
+            return status >= 200 && status < 300;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+function scopesCover(granted, required) {
+    if (!granted || !required)
+        return false;
+    const grantedSet = new Set(granted.split(' '));
+    return required.split(' ').every((scope) => grantedSet.has(scope));
+}
+/**
+ * Split on whitespace, dedupe, sort, join with spaces.
+ *
+ * Sorting keeps {@link scopesCover} and the stored value order-independent: the
+ * authorization server does not guarantee a stable order, and without normalization
+ * that would spuriously trigger re-registration.
+ */
+function normalizeScopes(raw) {
+    if (typeof raw !== 'string')
+        return undefined;
+    const parts = raw.trim().split(/\s+/).filter(Boolean);
+    if (!parts.length)
+        return undefined;
+    return Array.from(new Set(parts)).sort().join(' ');
+}
+function trimTrailingSlash(value) {
+    return value.endsWith('/') ? value.slice(0, -1) : value;
+}
+function query(params) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined)
+            search.append(key, value);
+    }
+    return search.toString();
+}
+function randomUrlSafe(numBytes) {
+    return randomBytes(numBytes).toString('base64url');
+}
+function s256(verifier) {
+    return createHash('sha256').update(verifier, 'ascii').digest('base64url');
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}