@pnpm/network.web-auth 1000.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015-2016 Rico Sta. Cruz and other contributors
+Copyright (c) 2016-2026 Zoltan Kochan and other contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/WebAuthTimeoutError.d.ts

@@ -0,0 +1,7 @@
+import { PnpmError } from '@pnpm/error';
+export declare class WebAuthTimeoutError extends PnpmError {
+    readonly endTime: number;
+    readonly startTime: number;
+    readonly timeout: number;
+    constructor(endTime: number, startTime: number, timeout: number);
+}

package/lib/WebAuthTimeoutError.js

@@ -0,0 +1,15 @@
+import { PnpmError } from '@pnpm/error';
+export class WebAuthTimeoutError extends PnpmError {
+    endTime;
+    startTime;
+    timeout;
+    constructor(endTime, startTime, timeout) {
+        super('WEBAUTH_TIMEOUT', 'Web-based authentication timed out before it could be completed', {
+            hint: 'Re-run this command and complete the authentication step in your browser before the time limit is reached',
+        });
+        this.endTime = endTime;
+        this.startTime = startTime;
+        this.timeout = timeout;
+    }
+}
+//# sourceMappingURL=WebAuthTimeoutError.js.map

package/lib/generateQrCode.d.ts

@@ -0,0 +1 @@
+export declare function generateQrCode(text: string): string;

package/lib/generateQrCode.js

@@ -0,0 +1,12 @@
+import qrcodeTerminal from 'qrcode-terminal';
+export function generateQrCode(text) {
+    let qrCode;
+    qrcodeTerminal.generate(text, { small: true }, (code) => {
+        qrCode = code;
+    });
+    if (qrCode != null)
+        return qrCode;
+    /* istanbul ignore next */
+    throw new Error('we were expecting qrcode-terminal to be fully synchronous, but it fails to execute the callback');
+}
+//# sourceMappingURL=generateQrCode.js.map

package/lib/index.d.ts

@@ -0,0 +1,4 @@
+export { generateQrCode } from './generateQrCode.js';
+export { pollForWebAuthToken, type PollForWebAuthTokenParams, type WebAuthContext, type WebAuthFetchOptions, type WebAuthFetchResponse, type WebAuthFetchResponseHeaders, } from './pollForWebAuthToken.js';
+export { WebAuthTimeoutError } from './WebAuthTimeoutError.js';
+export { isOtpError, type OtpContext, type OtpEnquirer, type OtpHandlingParams, OtpNonInteractiveError, type OtpPromptOptions, type OtpPromptResponse, OtpSecondChallengeError, SyntheticOtpError, withOtpHandling, } from './withOtpHandling.js';

package/lib/index.js

@@ -0,0 +1,5 @@
+export { generateQrCode } from './generateQrCode.js';
+export { pollForWebAuthToken, } from './pollForWebAuthToken.js';
+export { WebAuthTimeoutError } from './WebAuthTimeoutError.js';
+export { isOtpError, OtpNonInteractiveError, OtpSecondChallengeError, SyntheticOtpError, withOtpHandling, } from './withOtpHandling.js';
+//# sourceMappingURL=index.js.map

package/lib/pollForWebAuthToken.d.ts

@@ -0,0 +1,44 @@
+export interface WebAuthFetchOptions {
+    method: 'GET';
+    retry?: {
+        factor?: number;
+        maxTimeout?: number;
+        minTimeout?: number;
+        randomize?: boolean;
+        retries?: number;
+    };
+    timeout?: number;
+}
+export interface WebAuthFetchResponseHeaders {
+    get: (name: string) => string | null;
+}
+export interface WebAuthFetchResponse {
+    readonly headers: WebAuthFetchResponseHeaders;
+    readonly json: () => Promise<unknown>;
+    readonly ok: boolean;
+    readonly status: number;
+}
+export interface WebAuthContext {
+    Date: {
+        now: () => number;
+    };
+    setTimeout: (cb: () => void, ms: number) => void;
+    fetch: (url: string, options: WebAuthFetchOptions) => Promise<WebAuthFetchResponse>;
+}
+export interface PollForWebAuthTokenParams {
+    context: WebAuthContext;
+    doneUrl: string;
+    fetchOptions: WebAuthFetchOptions;
+    timeoutMs?: number;
+}
+/**
+ * Polls a registry's "done" URL until an authentication token is returned.
+ *
+ * The caller is responsible for displaying the authentication URL (and optional
+ * QR code) to the user before calling this function.
+ *
+ * @returns The authentication token string.
+ *
+ * @throws {@link WebAuthTimeoutError} if the timeout is exceeded.
+ */
+export declare function pollForWebAuthToken({ context: { Date, fetch, setTimeout }, doneUrl, fetchOptions, timeoutMs }: PollForWebAuthTokenParams): Promise<string>;

package/lib/pollForWebAuthToken.js

@@ -0,0 +1,66 @@
+import { WebAuthTimeoutError } from './WebAuthTimeoutError.js';
+/**
+ * Polls a registry's "done" URL until an authentication token is returned.
+ *
+ * The caller is responsible for displaying the authentication URL (and optional
+ * QR code) to the user before calling this function.
+ *
+ * @returns The authentication token string.
+ *
+ * @throws {@link WebAuthTimeoutError} if the timeout is exceeded.
+ */
+export async function pollForWebAuthToken({ context: { Date, fetch, setTimeout }, doneUrl, fetchOptions, timeoutMs = 5 * 60 * 1000, }) {
+    const startTime = Date.now();
+    const pollIntervalMs = 1000;
+    while (true) {
+        const now = Date.now();
+        if (now - startTime > timeoutMs) {
+            throw new WebAuthTimeoutError(now, startTime, timeoutMs);
+        }
+        // eslint-disable-next-line no-await-in-loop
+        await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+        let response;
+        try {
+            // eslint-disable-next-line no-await-in-loop
+            response = await fetch(doneUrl, fetchOptions);
+        }
+        catch {
+            continue;
+        }
+        if (!response.ok)
+            continue;
+        if (response.status === 202) {
+            // Registry is still waiting for authentication.
+            // Respect Retry-After header if present by waiting the additional time
+            // beyond the default poll interval already elapsed above, but do not
+            // exceed the overall timeout.
+            const retryAfterSeconds = Number(response.headers.get('retry-after'));
+            if (Number.isFinite(retryAfterSeconds)) {
+                const additionalMs = retryAfterSeconds * 1000 - pollIntervalMs;
+                if (additionalMs > 0) {
+                    const nowAfterPoll = Date.now();
+                    const remainingMs = timeoutMs - (nowAfterPoll - startTime);
+                    if (remainingMs <= 0) {
+                        throw new WebAuthTimeoutError(nowAfterPoll, startTime, timeoutMs);
+                    }
+                    const sleepMs = Math.min(additionalMs, remainingMs);
+                    // eslint-disable-next-line no-await-in-loop
+                    await new Promise(resolve => setTimeout(resolve, sleepMs));
+                }
+            }
+            continue;
+        }
+        let body;
+        try {
+            // eslint-disable-next-line no-await-in-loop
+            body = await response.json();
+        }
+        catch {
+            continue;
+        }
+        if (body.token) {
+            return body.token;
+        }
+    }
+}
+//# sourceMappingURL=pollForWebAuthToken.js.map

package/lib/withOtpHandling.d.ts

@@ -0,0 +1,74 @@
+import { PnpmError } from '@pnpm/error';
+import type { WebAuthFetchOptions, WebAuthFetchResponse } from './pollForWebAuthToken.js';
+export interface OtpEnquirer {
+    prompt: (options: OtpPromptOptions) => Promise<OtpPromptResponse | undefined>;
+}
+export interface OtpPromptOptions {
+    message: string;
+    name: 'otp';
+    type: 'input';
+}
+export interface OtpPromptResponse {
+    otp?: string;
+}
+interface OtpDate {
+    now: () => number;
+}
+export interface OtpContext {
+    Date: OtpDate;
+    setTimeout: (cb: () => void, ms: number) => void;
+    enquirer: OtpEnquirer;
+    fetch: (url: string, options: WebAuthFetchOptions) => Promise<WebAuthFetchResponse>;
+    globalInfo: (message: string) => void;
+    globalWarn: (message: string) => void;
+    process: Record<'stdin' | 'stdout', {
+        isTTY?: boolean;
+    }>;
+}
+interface OtpErrorBody {
+    authUrl?: string;
+    doneUrl?: string;
+}
+interface OtpError {
+    code: string;
+    body?: OtpErrorBody;
+}
+export declare const isOtpError: (error: unknown) => error is OtpError;
+export interface OtpHandlingParams<T> {
+    context: OtpContext;
+    fetchOptions: WebAuthFetchOptions;
+    operation: (otp?: string) => Promise<T>;
+}
+/**
+ * Wraps an operation with OTP (one-time password) challenge handling.
+ *
+ * When the operation throws an error with `code: 'EOTP'`, this function:
+ * 1. Uses the web-based authentication flow if the error body contains
+ *    `authUrl` and `doneUrl`.
+ * 2. Falls back to prompting the user for a classic OTP code.
+ * 3. Retries the operation with the obtained OTP.
+ *
+ * @throws {@link OtpNonInteractiveError} if OTP is required but the terminal is not interactive.
+ * @throws {@link OtpSecondChallengeError} if the registry requests OTP a second time after one was submitted.
+ * @throws the original error if OTP handling is not applicable.
+ *
+ * @see https://github.com/npm/cli/blob/7d900c46/lib/utils/otplease.js for npm's implementation.
+ */
+export declare function withOtpHandling<T>({ context, fetchOptions, operation }: OtpHandlingParams<T>): Promise<T>;
+/**
+ * Synthetic instance of {@link OtpError} meant to be thrown by the callbacks of {@link withOtpHandling}
+ * and caught and handled by {@link withOtpHandling}.
+ */
+export declare class SyntheticOtpError extends Error implements OtpError {
+    readonly code = "EOTP";
+    readonly body?: OtpErrorBody;
+    constructor(body: OtpErrorBody | undefined);
+    static fromUnknownBody(globalWarn: OtpContext['globalWarn'], body: unknown): SyntheticOtpError;
+}
+export declare class OtpNonInteractiveError extends PnpmError {
+    constructor();
+}
+export declare class OtpSecondChallengeError extends PnpmError {
+    constructor();
+}
+export {};

package/lib/withOtpHandling.js

@@ -0,0 +1,117 @@
+import { PnpmError } from '@pnpm/error';
+import { generateQrCode } from './generateQrCode.js';
+import { pollForWebAuthToken } from './pollForWebAuthToken.js';
+export const isOtpError = (error) => error != null &&
+    typeof error === 'object' &&
+    'code' in error &&
+    error.code === 'EOTP';
+/**
+ * Wraps an operation with OTP (one-time password) challenge handling.
+ *
+ * When the operation throws an error with `code: 'EOTP'`, this function:
+ * 1. Uses the web-based authentication flow if the error body contains
+ *    `authUrl` and `doneUrl`.
+ * 2. Falls back to prompting the user for a classic OTP code.
+ * 3. Retries the operation with the obtained OTP.
+ *
+ * @throws {@link OtpNonInteractiveError} if OTP is required but the terminal is not interactive.
+ * @throws {@link OtpSecondChallengeError} if the registry requests OTP a second time after one was submitted.
+ * @throws the original error if OTP handling is not applicable.
+ *
+ * @see https://github.com/npm/cli/blob/7d900c46/lib/utils/otplease.js for npm's implementation.
+ */
+export async function withOtpHandling({ context, fetchOptions, operation, }) {
+    const { enquirer, globalInfo, process, } = context;
+    try {
+        return await operation();
+    }
+    catch (error) {
+        if (!isOtpError(error))
+            throw error;
+        if (!process.stdin.isTTY || !process.stdout.isTTY) {
+            throw new OtpNonInteractiveError();
+        }
+        let otp;
+        if (error.body?.authUrl && error.body?.doneUrl) {
+            const qrCode = generateQrCode(error.body.authUrl);
+            globalInfo(`Authenticate your account at:\n${error.body.authUrl}\n\n${qrCode}`);
+            otp = await pollForWebAuthToken({
+                context,
+                doneUrl: error.body.doneUrl,
+                fetchOptions,
+            });
+        }
+        else {
+            const enquirerResponse = await enquirer.prompt({
+                message: 'This operation requires a one-time password.\nEnter OTP:',
+                name: 'otp',
+                type: 'input',
+            });
+            // Use || (not ??) so that empty-string input is treated as "no OTP provided"
+            otp = enquirerResponse?.otp || undefined;
+        }
+        if (otp != null) {
+            try {
+                return await operation(otp);
+            }
+            catch (retryError) {
+                if (isOtpError(retryError)) {
+                    throw new OtpSecondChallengeError();
+                }
+                throw retryError;
+            }
+        }
+        throw error;
+    }
+}
+/**
+ * Synthetic instance of {@link OtpError} meant to be thrown by the callbacks of {@link withOtpHandling}
+ * and caught and handled by {@link withOtpHandling}.
+ */
+export class SyntheticOtpError extends Error {
+    code = 'EOTP';
+    body;
+    constructor(body) {
+        super('This error was meant to be caught by `withOtpHandling`, not to propagate to other parts of the code');
+        this.body = body;
+    }
+    static fromUnknownBody(globalWarn, body) {
+        if (body == null || typeof body !== 'object') {
+            return new SyntheticOtpError(undefined);
+        }
+        let authUrl;
+        let doneUrl;
+        if ('authUrl' in body) {
+            if (typeof body.authUrl === 'string') {
+                authUrl = body.authUrl;
+            }
+            else {
+                globalWarn(`OTP error body: authUrl has type ${typeof body.authUrl}, expected string`);
+            }
+        }
+        if ('doneUrl' in body) {
+            if (typeof body.doneUrl === 'string') {
+                doneUrl = body.doneUrl;
+            }
+            else {
+                globalWarn(`OTP error body: doneUrl has type ${typeof body.doneUrl}, expected string`);
+            }
+        }
+        return new SyntheticOtpError({ authUrl, doneUrl });
+    }
+}
+export class OtpNonInteractiveError extends PnpmError {
+    constructor() {
+        super('OTP_NON_INTERACTIVE', 'The registry requires additional authentication, but pnpm is not running in an interactive terminal', {
+            hint: 'Re-run this command in an interactive terminal to complete authentication, or provide the --otp option if you are using a classic one-time password (OTP)',
+        });
+    }
+}
+export class OtpSecondChallengeError extends PnpmError {
+    constructor() {
+        super('OTP_SECOND_CHALLENGE', 'The registry requested a one-time password (OTP) a second time after one was already provided', {
+            hint: 'This is unexpected behavior from the registry. Try the command again later and, if the issue persists, verify that your registry supports OTP-based authentication or contact the registry administrator.',
+        });
+    }
+}
+//# sourceMappingURL=withOtpHandling.js.map

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@pnpm/network.web-auth",
+  "version": "1000.0.0",
+  "description": "Web-based authentication flow with QR code display and token polling",
+  "keywords": [
+    "pnpm",
+    "pnpm11",
+    "auth"
+  ],
+  "license": "MIT",
+  "funding": "https://opencollective.com/pnpm",
+  "repository": "https://github.com/pnpm/pnpm/tree/main/network/web-auth",
+  "homepage": "https://github.com/pnpm/pnpm/tree/main/network/web-auth#readme",
+  "bugs": {
+    "url": "https://github.com/pnpm/pnpm/issues"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "files": [
+    "lib",
+    "!*.map"
+  ],
+  "dependencies": {
+    "qrcode-terminal": "^0.12.0",
+    "@pnpm/error": "1000.0.5"
+  },
+  "devDependencies": {
+    "@jest/globals": "30.3.0",
+    "@types/qrcode-terminal": "^0.12.2",
+    "@pnpm/network.web-auth": "1000.0.0"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "jest": {
+    "preset": "@pnpm/jest-config"
+  },
+  "scripts": {
+    "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\"",
+    "test": "pn compile && pn .test",
+    "compile": "tsgo --build && pn lint --fix",
+    ".test": "cross-env NODE_OPTIONS=\"$NODE_OPTIONS --experimental-vm-modules --disable-warning=ExperimentalWarning --disable-warning=DEP0169\" jest"
+  }
+}