@vltpkg/registry-client 1.0.0-rc.22 → 1.0.0-rc.24

package/dist/index.d.ts

@@ -0,0 +1,145 @@
+import { Cache } from '@vltpkg/cache';
+import type { Integrity } from '@vltpkg/types';
+import type { Dispatcher } from 'undici';
+import { RetryAgent } from 'undici';
+import type { Token } from './auth.ts';
+import { clearRuntimeTokens, deleteToken, getKC, isToken, keychains, runtimeTokens, setRuntimeToken, setToken } from './auth.ts';
+import type { JSONObj } from './cache-entry.ts';
+import { CacheEntry } from './cache-entry.ts';
+import type { TokenResponse } from './token-response.ts';
+import type { WebAuthChallenge } from './web-auth-challenge.ts';
+import { oidc } from './oidc.ts';
+import type { OidcOptions } from './oidc.ts';
+export { CacheEntry, clearRuntimeTokens, deleteToken, getKC, isToken, keychains, oidc, runtimeTokens, setRuntimeToken, setToken, type JSONObj, type OidcOptions, type Token, type TokenResponse, type WebAuthChallenge, };
+export type CacheableMethod = 'GET' | 'HEAD';
+export declare const isCacheableMethod: (m: unknown) => m is CacheableMethod;
+export type RegistryClientOptions = {
+    /**
+     * Path on disk where the cache should be stored
+     *
+     * Defaults to the XDG cache folder for `vlt/registry-client`
+     */
+    cache?: string;
+    /**
+     * Number of retries to perform when encountering network errors or
+     * likely-transient errors from git hosts.
+     */
+    'fetch-retries'?: number;
+    /** The exponential backoff factor to use when retrying git hosts */
+    'fetch-retry-factor'?: number;
+    /** Number of milliseconds before starting first retry */
+    'fetch-retry-mintimeout'?: number;
+    /** Maximum number of milliseconds between two retries */
+    'fetch-retry-maxtimeout'?: number;
+    /** the identity to use for storing auth tokens */
+    identity?: string;
+    /**
+     * If the server does not serve a `stale-while-revalidate` value in the
+     * `cache-control` header, then this multiplier is applied to the `max-age`
+     * or `s-maxage` values.
+     *
+     * By default, this is `60`, so for example a response that is cacheable for
+     * 5 minutes will allow a stale response while revalidating for up to 5
+     * hours.
+     *
+     * If the server *does* provide a `stale-while-revalidate` value, then that
+     * is always used.
+     *
+     * Set to 0 to prevent any `stale-while-revalidate` behavior unless
+     * explicitly allowed by the server's `cache-control` header.
+     */
+    'stale-while-revalidate-factor'?: number;
+};
+export type RegistryClientRequestOptions = Omit<Dispatcher.RequestOptions, 'method' | 'path'> & {
+    /**
+     * `path` should not be set when using the RegistryClient.
+     * It will be overwritten with the path on the URL being requested.
+     * This only here for compliance with the DispatchOptions base type.
+     * @deprecated
+     */
+    path?: string;
+    /**
+     * Method is optional, defaults to 'GET'
+     */
+    method?: Dispatcher.DispatchOptions['method'];
+    /**
+     * Provide an SRI string to verify integrity of the item being fetched.
+     *
+     * This is only relevant when it must make a request to the registry. Once in
+     * the local disk cache, items are assumed to be trustworthy.
+     */
+    integrity?: Integrity;
+    /**
+     * Set to true if the integrity should be trusted implicitly without
+     * a recalculation, for example if it comes from a trusted registry that
+     * also serves the tarball itself.
+     */
+    trustIntegrity?: boolean;
+    /**
+     * Follow up to 10 redirections by default. Set this to 0 to just return
+     * the 3xx response. If the max redirections are expired, and we still get
+     * a redirection response, then fail the request. Redirection cycles are
+     * always treated as an error.
+     */
+    maxRedirections?: number;
+    /**
+     * the number of redirections that have already been seen. This is used
+     * internally, and should always start at 0.
+     * @internal
+     */
+    redirections?: Set<string>;
+    /**
+     * Set to `false` to suppress ANY lookups from cache. This will also
+     * prevent storing the result to the cache.
+     */
+    useCache?: false;
+    /**
+     * Set to pass an `npm-otp` header on the request.
+     *
+     * This should not be set except by the RegistryClient itself, when
+     * we receive a 401 response with an OTP challenge.
+     * @internal
+     */
+    otp?: string;
+    /**
+     * Set to false to explicitly prevent `stale-while-revalidate` behavior,
+     * for use in revalidating while stale.
+     * @internal
+     */
+    staleWhileRevalidate?: false;
+};
+export declare const userAgent: string;
+export declare class RegistryClient {
+    #private;
+    agent: RetryAgent;
+    cache: Cache;
+    identity: string;
+    staleWhileRevalidateFactor: number;
+    constructor(options: RegistryClientOptions);
+    /**
+     * Fetch the entire set of a paginated list of objects
+     */
+    scroll<T>(url: URL | string, options?: RegistryClientRequestOptions, seek?: (obj: T) => boolean): Promise<T[]>;
+    /**
+     * find a given item in a paginated set
+     */
+    seek<T>(url: URL | string, seek: (obj: T) => boolean, options?: RegistryClientRequestOptions): Promise<T | undefined>;
+    /**
+     * Log out from the registry specified, attempting to destroy the
+     * token if the registry supports that endpoint.
+     */
+    logout(registry: string): Promise<void>;
+    /**
+     * Log into the registry specified
+     *
+     * Does not return the token or expose it, just saves to the auth keychain
+     * and returns void if it worked. Otherwise, error is raised.
+     */
+    login(registry: string): Promise<void>;
+    /**
+     * Given a {@link WebAuthChallenge}, open the `authUrl` in a browser and
+     * hang on the `doneUrl` until it returns a {@link TokenResponse} object.
+     */
+    webAuthOpener({ doneUrl, authUrl }: WebAuthChallenge): Promise<TokenResponse>;
+    request(url: URL | string, options?: RegistryClientRequestOptions): Promise<CacheEntry>;
+}

package/dist/index.js

@@ -0,0 +1,326 @@
+import { Cache } from '@vltpkg/cache';
+import { register as cacheUnzipRegister } from '@vltpkg/cache-unzip';
+import { error } from '@vltpkg/error-cause';
+import { asError } from '@vltpkg/types';
+import { logRequest } from '@vltpkg/output';
+import { urlOpen } from '@vltpkg/url-open';
+import { XDG } from '@vltpkg/xdg';
+import { dirname, resolve } from 'node:path';
+import { setTimeout } from 'node:timers/promises';
+import { loadPackageJson } from 'package-json-from-dist';
+import { Agent, RetryAgent } from 'undici';
+import { addHeader } from "./add-header.js";
+import { clearRuntimeTokens, deleteToken, getKC, getToken, isToken, keychains, runtimeTokens, setRuntimeToken, setToken, } from "./auth.js";
+import { CacheEntry } from "./cache-entry.js";
+import { register } from "./cache-revalidate.js";
+import { bun, deno, node } from "./env.js";
+import { handleCacheHitResponse } from "./handle-304-response.js";
+import { otplease } from "./otplease.js";
+import { isRedirect, redirect } from "./redirect.js";
+import { setCacheHeaders } from "./set-cache-headers.js";
+import { getTokenResponse } from "./token-response.js";
+import { getWebAuthChallenge } from "./web-auth-challenge.js";
+import { getEncondedValue } from "./string-encoding.js";
+import { oidc } from "./oidc.js";
+export { CacheEntry, clearRuntimeTokens, deleteToken, getKC, isToken, keychains, oidc, runtimeTokens, setRuntimeToken, setToken, };
+export const isCacheableMethod = (m) => m === 'GET' || m === 'HEAD';
+const { version } = loadPackageJson(import.meta.filename, process.env.__VLT_INTERNAL_REGISTRY_CLIENT_PACKAGE_JSON);
+const nua = globalThis.navigator?.userAgent ??
+    (bun ? `Bun/${bun}`
+        : deno ? `Deno/${deno}`
+            : node ? `Node.js/${node}`
+                : '(unknown platform)');
+export const userAgent = `@vltpkg/registry-client/${version} ${nua}`;
+const agentOptions = {
+    bodyTimeout: 600_000,
+    headersTimeout: 600_000,
+    keepAliveMaxTimeout: 1_200_000,
+    keepAliveTimeout: 600_000,
+    keepAliveTimeoutThreshold: 30_000,
+    connect: {
+        timeout: 600_000,
+        keepAlive: true,
+        keepAliveInitialDelay: 30_000,
+        sessionTimeout: 600,
+    },
+    connections: 128,
+    pipelining: 10,
+};
+const xdg = new XDG('vlt');
+export class RegistryClient {
+    agent;
+    cache;
+    identity;
+    staleWhileRevalidateFactor;
+    constructor(options) {
+        const { cache = xdg.cache(), 'fetch-retry-factor': timeoutFactor = 2, 'fetch-retry-mintimeout': minTimeout = 0, 'fetch-retry-maxtimeout': maxTimeout = 30_000, 'fetch-retries': maxRetries = 3, identity = '', 'stale-while-revalidate-factor': staleWhileRevalidateFactor = 576, // 48h for a 5min cache
+         } = options;
+        this.identity = identity;
+        this.staleWhileRevalidateFactor = staleWhileRevalidateFactor;
+        const path = resolve(cache, 'registry-client');
+        this.cache = new Cache({
+            path,
+            onDiskWrite(_path, key, data) {
+                if (CacheEntry.isGzipEntry(data)) {
+                    cacheUnzipRegister(path, key);
+                }
+            },
+        });
+        const dispatch = new Agent(agentOptions);
+        this.agent = new RetryAgent(dispatch, {
+            maxRetries,
+            timeoutFactor,
+            minTimeout,
+            maxTimeout,
+            retryAfter: true,
+            errorCodes: [
+                'ECONNREFUSED',
+                'ECONNRESET',
+                'EHOSTDOWN',
+                'ENETDOWN',
+                'ENETUNREACH',
+                'ENOTFOUND',
+                'EPIPE',
+                'UND_ERR_SOCKET',
+            ],
+        });
+    }
+    /**
+     * Fetch the entire set of a paginated list of objects
+     */
+    async scroll(url, options = {}, seek) {
+        const resp = await this.request(url, options);
+        const { objects, urls } = resp.json();
+        // if we have more, and haven't found our target, fetch more
+        return urls.next && !(seek && objects.some(seek)) ?
+            objects.concat(await this.scroll(urls.next, options, seek))
+            : objects;
+    }
+    /**
+     * find a given item in a paginated set
+     */
+    async seek(url, seek, options = {}) {
+        return (await this.scroll(url, options, seek)).find(seek);
+    }
+    /**
+     * Log out from the registry specified, attempting to destroy the
+     * token if the registry supports that endpoint.
+     */
+    async logout(registry) {
+        // if we have no token for that registry, nothing to do
+        const tok = await getToken(registry, this.identity);
+        if (!tok)
+            return;
+        const s = tok.replace(/^(Bearer|Basic) /i, '');
+        const tokensUrl = new URL('-/npm/v1/tokens', registry);
+        const record = await this.seek(tokensUrl, ({ token }) => s.startsWith(token), {
+            useCache: false,
+        }).catch(() => undefined);
+        if (record) {
+            const { key } = record;
+            await this.request(new URL(`-/npm/v1/tokens/token/${key}`, registry), { useCache: false, method: 'DELETE' });
+        }
+        await deleteToken(registry, this.identity);
+    }
+    /**
+     * Log into the registry specified
+     *
+     * Does not return the token or expose it, just saves to the auth keychain
+     * and returns void if it worked. Otherwise, error is raised.
+     */
+    async login(registry) {
+        // - make POST to '/-/v1/login'
+        // - include a body of {} and npm-auth-type:web
+        // - get a {doneUrl, authUrl}
+        // - open the authUrl
+        // - hang on the doneUrl until done
+        //
+        // if that fails: fall back to couchdb login
+        const webLoginURL = new URL('-/v1/login', registry);
+        const response = await this.request(webLoginURL, {
+            method: 'POST',
+            useCache: false,
+            headers: {
+                'content-type': 'application/json',
+                'npm-auth-type': 'web',
+            },
+            body: '{}',
+        });
+        if (response.statusCode === 200) {
+            const challenge = getWebAuthChallenge(response.json());
+            if (challenge) {
+                const result = await this.webAuthOpener(challenge);
+                await setToken(registry, `Bearer ${result.token}`, this.identity);
+                return;
+            }
+        }
+        /* c8 ignore start */
+        // TODO: fall back to username/password login, and/or couchdb PUT login
+        throw error('Failed to perform web login', { response });
+    }
+    /* c8 ignore stop */
+    /**
+     * Given a {@link WebAuthChallenge}, open the `authUrl` in a browser and
+     * hang on the `doneUrl` until it returns a {@link TokenResponse} object.
+     */
+    async webAuthOpener({ doneUrl, authUrl }) {
+        const ac = new AbortController();
+        const { signal } = ac;
+        /* c8 ignore start - race condition */
+        const [result] = await Promise.all([
+            this.#checkLogin(doneUrl, { signal }).then(result => {
+                ac.abort();
+                return result;
+            }),
+            urlOpen(authUrl, { signal }).catch((er) => {
+                if (asError(er).name === 'AbortError')
+                    return;
+                ac.abort();
+                throw er;
+            }),
+        ]);
+        /* c8 ignore stop */
+        return result;
+    }
+    async #checkLogin(url, options = {}) {
+        const response = await this.request(url, {
+            ...options,
+            useCache: false,
+        });
+        const { signal } = options;
+        if (response.statusCode === 202) {
+            const rt = response.getHeaderString('retry-after');
+            const retryAfter = rt ? Number(rt) : -1;
+            if (retryAfter > 0) {
+                await setTimeout(retryAfter * 1000, null, { signal });
+            }
+            return await this.#checkLogin(url, options);
+        }
+        if (response.statusCode === 200) {
+            const token = getTokenResponse(response.json());
+            if (token)
+                return token;
+        }
+        throw error('Invalid response from web login endpoint', {
+            response,
+        });
+    }
+    async request(url, options = {}) {
+        const u = typeof url === 'string' ? new URL(url) : url;
+        const { method = 'GET', integrity, redirections = new Set(), signal, otp = (process.env.VLT_OTP ?? '').trim(), staleWhileRevalidate = true, } = options;
+        let { trustIntegrity } = options;
+        const m = isCacheableMethod(method) ? method : undefined;
+        const { useCache = !!m } = options;
+        signal?.throwIfAborted();
+        // first, try to get from the cache before making any request.
+        const { origin } = u;
+        const key = `${method !== 'GET' ? method + ' ' : ''}${u}`;
+        const buffer = useCache ?
+            await this.cache.fetch(key, { context: { integrity } })
+            : undefined;
+        const entry = buffer ? CacheEntry.decode(buffer) : undefined;
+        if (entry?.valid) {
+            logRequest(url, 'cache');
+            return entry;
+        }
+        if (staleWhileRevalidate && entry?.staleWhileRevalidate && m) {
+            // revalidate while returning the stale entry
+            register(dirname(this.cache.path()), m, url);
+            logRequest(url, 'stale');
+            return entry;
+        }
+        logRequest(url, 'start');
+        // either no cache entry, or need to revalidate before use.
+        setCacheHeaders(options, entry);
+        redirections.add(String(url));
+        Object.assign(options, {
+            path: u.pathname.replace(/\/+$/, '') + u.search,
+            ...agentOptions,
+        });
+        options.origin = u.origin;
+        options.headers = addHeader(addHeader(options.headers, 'accept-encoding', 'gzip;q=1.0, identity;q=0.5'), 'user-agent', userAgent);
+        if (otp) {
+            options.headers = addHeader(options.headers, 'npm-otp', otp);
+        }
+        if (integrity) {
+            options.headers = addHeader(options.headers, 'accept-integrity', integrity);
+        }
+        options.method = options.method ?? 'GET';
+        // will remove if we don't have a token.
+        options.headers = addHeader(options.headers, 'authorization', await getToken(origin, this.identity));
+        let response = null;
+        try {
+            response = await this.agent.request(options);
+            /* c8 ignore start */
+        }
+        catch (er) {
+            // Rethrow so we get a better stack trace
+            throw error('Request failed', {
+                code: 'EREQUEST',
+                cause: er,
+                url,
+                method,
+            });
+        }
+        /* c8 ignore stop */
+        const result = await this.#handleResponse(u, options, response, entry);
+        if (result.getHeader('integrity')) {
+            trustIntegrity = true;
+        }
+        if (result.isGzip && !trustIntegrity) {
+            result.checkIntegrity({ url });
+        }
+        if (useCache) {
+            // Get the encoded buffer from the cache entry
+            const buffer = result.encode();
+            this.cache.set(key, Buffer.from(buffer.buffer, buffer.byteOffset, buffer.byteLength), {
+                integrity: result.integrity,
+            });
+        }
+        return result;
+    }
+    async #handleResponse(url, options, response, entry) {
+        if (handleCacheHitResponse(response, entry))
+            return entry;
+        if (response.statusCode === 401) {
+            const repeatRequest = await otplease(this, options, response);
+            if (repeatRequest)
+                return await this.request(url, repeatRequest);
+        }
+        const h = [];
+        for (const [key, value] of Object.entries(response.headers)) {
+            /* c8 ignore start - theoretical */
+            if (Array.isArray(value)) {
+                h.push(getEncondedValue(key), getEncondedValue(value.join(', ')));
+                /* c8 ignore stop */
+            }
+            else if (typeof value === 'string') {
+                h.push(getEncondedValue(key), getEncondedValue(value));
+            }
+        }
+        const { integrity, trustIntegrity } = options;
+        const result = new CacheEntry(
+        /* c8 ignore next - should always have a status code */
+        response.statusCode || 200, h, {
+            integrity,
+            trustIntegrity,
+            'stale-while-revalidate-factor': this.staleWhileRevalidateFactor,
+            contentLength: response.headers['content-length'] ?
+                Number(response.headers['content-length'])
+                : /* c8 ignore next */ undefined,
+        });
+        if (isRedirect(result)) {
+            response.body.resume();
+            const [nextURL, nextOptions] = redirect(options, result, url);
+            if (nextOptions && nextURL) {
+                return await this.request(nextURL, nextOptions);
+            }
+            return result;
+        }
+        response.body.on('data', (chunk) => result.addBody(chunk));
+        return await new Promise((res, rej) => {
+            response.body.on('error', rej);
+            response.body.on('end', () => res(result));
+        });
+    }
+}

package/dist/is-cacheable.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Determine whether we're allowed to cache it, based on status code
+ */
+export declare const isCacheable: (statusCode: number) => boolean;

package/dist/is-cacheable.js

@@ -0,0 +1,9 @@
+/**
+ * Determine whether we're allowed to cache it, based on status code
+ */
+export const isCacheable = (statusCode) => statusCode < 200 ? false
+    : statusCode < 300 ? true
+        : statusCode === 301 ? true
+            : statusCode === 308 ? true
+                : statusCode === 410 ? true
+                    : false;

package/dist/is-iterable.d.ts

@@ -0,0 +1 @@
+export declare const isIterable: <T>(o: unknown) => o is Iterable<T>;

package/dist/is-iterable.js

@@ -0,0 +1 @@
+export const isIterable = (o) => !!o && typeof o === 'object' && Symbol.iterator in o;

package/dist/oidc.d.ts

@@ -0,0 +1,17 @@
+import type { Token } from './auth.ts';
+export type OidcOptions = {
+    /** The package name being published, e.g. `@scope/name` */
+    packageName: string;
+    /** The full registry URL, e.g. `https://registry.npmjs.org/` */
+    registry: string;
+};
+/**
+ * Detect CI environment and exchange an OIDC ID token for a
+ * registry auth token. Sets the token into the runtime token
+ * store so subsequent requests are authenticated.
+ *
+ * This function **never throws**. OIDC is always optional — if
+ * it is unavailable or any step fails the function returns
+ * `undefined` silently.
+ */
+export declare const oidc: (opts: OidcOptions) => Promise<Token | undefined>;

package/dist/oidc.js

@@ -0,0 +1,151 @@
+import { request } from 'undici';
+import { setRuntimeToken } from "./auth.js";
+const log = (...args) => 
+// eslint-disable-next-line no-console
+console.error('[vlt:oidc]', ...args);
+/**
+ * Safely parse a JSON response body, returning undefined on failure.
+ */
+const safeJson = async (res) => {
+    try {
+        return (await res.body.json());
+        /* c8 ignore next 3 - defensive: non-JSON response body */
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Keys that are always replaced with '[REDACTED]' before logging.
+ */
+const SENSITIVE_KEYS = new Set(['token', 'value', 'secret', 'key']);
+/**
+ * Recursively redact sensitive fields from a value before logging.
+ * Works as a JSON.stringify replacer so nested objects are handled
+ * automatically — no sensitive value is ever serialised.
+ */
+const redact = (obj) => JSON.parse(JSON.stringify(obj, (k, v) => SENSITIVE_KEYS.has(k) ? '[REDACTED]' : v));
+/**
+ * Detect CI environment and exchange an OIDC ID token for a
+ * registry auth token. Sets the token into the runtime token
+ * store so subsequent requests are authenticated.
+ *
+ * This function **never throws**. OIDC is always optional — if
+ * it is unavailable or any step fails the function returns
+ * `undefined` silently.
+ */
+export const oidc = async (opts) => {
+    try {
+        return await _oidc(opts);
+    }
+    catch (err) /* c8 ignore start - defensive */ {
+        log('Unexpected error:', err instanceof Error ? err.message : String(err));
+        return undefined;
+    } /* c8 ignore stop */
+};
+const _oidc = async ({ packageName, registry, }) => {
+    const isGitHub = process.env.GITHUB_ACTIONS === 'true';
+    const isGitLab = process.env.GITLAB_CI === 'true';
+    const isCircle = process.env.CIRCLECI === 'true';
+    log(`CI detected: github=${isGitHub} gitlab=${isGitLab} circle=${isCircle}`);
+    if (!isGitHub && !isGitLab && !isCircle) {
+        log('Not in a supported CI environment — skipping');
+        return undefined;
+    }
+    // NPM_ID_TOKEN is supported as an override in all CI environments
+    let idToken = process.env.NPM_ID_TOKEN;
+    log(`NPM_ID_TOKEN: ${idToken ? `set (length=${idToken.length})` : 'not set'}`);
+    if (!idToken && isGitHub) {
+        idToken = await fetchGitHubIdToken(registry);
+    }
+    if (!idToken) {
+        log('No ID token available — skipping');
+        return undefined;
+    }
+    const token = await exchangeToken(idToken, packageName, registry);
+    if (token) {
+        setRuntimeToken(registry, token);
+        log(`Token set for registry ${registry}`);
+    }
+    else {
+        log('Token exchange did not return a token');
+    }
+    return token;
+};
+/**
+ * Fetch an OIDC ID token from GitHub Actions.
+ * Requires `id-token: write` permission in the workflow.
+ */
+const fetchGitHubIdToken = async (registry) => {
+    const requestUrl = process.env.ACTIONS_ID_TOKEN_REQUEST_URL;
+    const requestToken = process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;
+    log(`ACTIONS_ID_TOKEN_REQUEST_URL: ${requestUrl ? `set (length=${requestUrl.length})` : 'not set — skipping (missing id-token permissions?)'}`);
+    log(`ACTIONS_ID_TOKEN_REQUEST_TOKEN: ${requestToken ? 'set' : 'not set'}`);
+    if (!requestUrl || !requestToken) {
+        return undefined;
+    }
+    const audience = `npm:${new URL(registry).hostname}`;
+    const url = new URL(requestUrl);
+    url.searchParams.append('audience', audience);
+    log(`Fetching GitHub ID token with audience ${audience}`);
+    try {
+        const res = await request(url, {
+            method: 'GET',
+            headers: {
+                accept: 'application/json',
+                authorization: `Bearer ${requestToken}`,
+            },
+        });
+        log(`GitHub ID token response: status=${res.statusCode}`);
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+            const body = await safeJson(res);
+            log(`GitHub ID token error body: ${body ? JSON.stringify(redact(body)) : '(non-JSON response)'}`);
+            return undefined;
+        }
+        const json = await safeJson(res);
+        const value = json?.value;
+        log(`GitHub ID token: hasValue=${!!value}`);
+        return value || undefined;
+    }
+    catch (err) /* c8 ignore start - network error */ {
+        log('GitHub ID token fetch error:', err instanceof Error ? err.message : String(err));
+        return undefined;
+    } /* c8 ignore stop */
+};
+/**
+ * Exchange an OIDC ID token for an npm auth token via the
+ * registry token exchange endpoint.
+ */
+const exchangeToken = async (idToken, packageName, registry) => {
+    // npm escaping: @scope/name → @scope%2Fname
+    const escapedName = packageName.replace('/', '%2F');
+    const exchangeUrl = new URL(`/-/npm/v1/oidc/token/exchange/package/${escapedName}`, registry);
+    log(`Exchanging token for package: ${packageName}`);
+    log(`Exchange URL: ${exchangeUrl.href}`);
+    try {
+        const res = await request(exchangeUrl, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${idToken}`,
+            },
+        });
+        log(`Exchange response: status=${res.statusCode}`);
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+            const body = await safeJson(res);
+            log(`Exchange error body: ${body ? JSON.stringify(redact(body)) : '(non-JSON response)'}`);
+            return undefined;
+        }
+        const json = await safeJson(res);
+        const hasToken = !!json?.token;
+        log(`Exchange result: hasToken=${hasToken}`);
+        if (!json?.token || typeof json.token !== 'string') {
+            return undefined;
+        }
+        return `Bearer ${json.token}`;
+    }
+    catch (err) /* c8 ignore start - network error */ {
+        log('Exchange request error:', err instanceof Error ? err.message : String(err));
+        return undefined;
+    } /* c8 ignore stop */
+};

package/dist/otplease.d.ts

@@ -0,0 +1,3 @@
+import type { Dispatcher } from 'undici';
+import type { RegistryClient, RegistryClientRequestOptions } from './index.ts';
+export declare const otplease: (client: RegistryClient, options: RegistryClientRequestOptions, response: Dispatcher.ResponseData) => Promise<RegistryClientRequestOptions | undefined>;