@cloudflare/workers-auth 0.5.6 → 0.6.0

package/dist/cf/index.d.mts

@@ -1,6 +1,6 @@
-import { a as ConfigStorage, A as AuthConfigStorage, U as UserAuthConfig, b as OAuthFlowContext, k as ProfileStore } from '../file-format-B1KgHuUR.mjs';
-import { C as CliDescriptor, U as UserPreferences, A as AuthContext, a as CloudflareAuth, K as KeyringPreferenceContext, S as SetKeyringPreferenceResult } from '../keyring-preference-BgjU5DM9.mjs';
-export { b as CloudflareLoginProps } from '../keyring-preference-BgjU5DM9.mjs';
+import { a as ConfigStorage, A as AuthConfigStorage, U as UserAuthConfig, b as OAuthFlowContext, k as ProfileStore } from '../file-format-Dbmn5hhd.mjs';
+import { C as CliDescriptor, U as UserPreferences, A as AuthContext, a as CloudflareAuth, K as KeyringPreferenceContext, S as SetKeyringPreferenceResult } from '../keyring-preference-CeP6MLyb.mjs';
+export { b as CloudflareLoginProps } from '../keyring-preference-CeP6MLyb.mjs';
 import '@cloudflare/workers-utils';
 
 /**

package/dist/cf/index.mjs

@@ -1,5 +1,5 @@
-import { createAuthConfigFileHelpers, createPreferences, createKeyringPreference, createFileStorage, createCloudflareAuth, createCloudflareProfileStore } from '../chunk-CEH7NWR7.mjs';
-import '../chunk-7ZPLVMOI.mjs';
+import { createAuthConfigFileHelpers, createPreferences, createKeyringPreference, createFileStorage, createCloudflareAuth, createCloudflareProfileStore } from '../chunk-AEOSGWMT.mjs';
+import '../chunk-7AYQ2BAF.mjs';
 import { __name } from '../chunk-O6YSETKJ.mjs';
 import { getEnvironmentVariableFactory, getGlobalConfigPath, getCloudflareApiEnvironmentFromEnv } from '@cloudflare/workers-utils';
 import path from 'node:path';
@@ -7,6 +7,7 @@ import path from 'node:path';
 // src/cf/constants.ts
 var CF_KEYRING_SERVICE_NAME = "cloudflare";
 var CF_CLI_NAME = "cf";
+var CF_DISPLAY_NAME = "cf";
 var CF_OAUTH_CALLBACK_URL = "http://localhost:8877/oauth/callback";
 var CF_CONSENT_PAGES = {
   granted: {
@@ -158,10 +159,12 @@ var {
 // src/cf/index.ts
 var CF_CLI = {
   cliName: CF_CLI_NAME,
+  displayName: CF_DISPLAY_NAME,
   commands: {
     login: "cf auth login",
     whoami: "cf auth whoami",
-    createProfile: "cf auth create"
+    createProfile: "cf auth create",
+    deviceLogin: "cf auth login --device"
   },
   keyringServiceName: CF_KEYRING_SERVICE_NAME,
   clientId: getClientIdFromEnv,

package/dist/{chunk-7ZPLVMOI.mjs → chunk-7AYQ2BAF.mjs}

@@ -143,6 +143,11 @@ function getCloudflareAccountIdFromEnv() {
   );
 }
 __name(getCloudflareAccountIdFromEnv, "getCloudflareAccountIdFromEnv");
+var DEVICE_AUTH_PATH = "/oauth2/device/auth";
+function getDeviceAuthUrl() {
+  return `https://${getAuthDomainFromEnv()}${DEVICE_AUTH_PATH}`;
+}
+__name(getDeviceAuthUrl, "getDeviceAuthUrl");
 var getAccessClientIdFromEnv = getEnvironmentVariableFactory({
   variableName: "CLOUDFLARE_ACCESS_CLIENT_ID"
 });
@@ -320,6 +325,36 @@ async function generatePKCECodes() {
   return { codeChallenge, codeVerifier };
 }
 __name(generatePKCECodes, "generatePKCECodes");
+var generateVerificationUrl = /* @__PURE__ */ __name(({
+  verificationUri,
+  userCode
+}) => {
+  const url2 = new URL(verificationUri);
+  url2.searchParams.set("user_code", userCode);
+  return url2.toString();
+}, "generateVerificationUrl");
+function parseUrl(value) {
+  try {
+    return new URL(value);
+  } catch {
+    return void 0;
+  }
+}
+__name(parseUrl, "parseUrl");
+function assertTrustedVerificationUrl(verificationUrl, options) {
+  const url2 = parseUrl(verificationUrl);
+  const expected = parseUrl(`https://${options.authDomain}`);
+  const trusted = url2 !== void 0 && expected !== void 0 && url2.protocol === "https:" && url2.username === "" && url2.password === "" && // `host` rather than `hostname` so a port in either value is significant.
+  url2.host === expected.host;
+  if (!trusted) {
+    throw new UserError(
+      `The authorization server returned an untrusted \`${options.field}\`: ${verificationUrl}
+Expected an \`https\` URL on \`${options.authDomain}\`. Refusing to display or open it.`,
+      { telemetryMessage: "user device-flow untrusted verification url" }
+    );
+  }
+}
+__name(assertTrustedVerificationUrl, "assertTrustedVerificationUrl");
 
 // src/generate-auth-url.ts
 var generateAuthUrl = /* @__PURE__ */ __name(({
@@ -1201,6 +1236,318 @@ If you have changed the callback host or port because you are running in a conta
   return Promise.race([timerPromise, loginPromise]);
 }
 __name(getOauthToken, "getOauthToken");
+var DEVICE_FLOW_MAX_DURATION_SECONDS = 300;
+var DEVICE_FLOW_MIN_POLL_INTERVAL_SECONDS = 1;
+function getStringMember(body, key) {
+  if (typeof body !== "object" || body === null) {
+    return void 0;
+  }
+  const value = body[key];
+  return typeof value === "string" && value !== "" ? value : void 0;
+}
+__name(getStringMember, "getStringMember");
+function getPositiveNumberMember(body, key) {
+  if (typeof body !== "object" || body === null) {
+    return void 0;
+  }
+  const value = body[key];
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : void 0;
+}
+__name(getPositiveNumberMember, "getPositiveNumberMember");
+function describeUnusableResponse(response, body) {
+  const status = `HTTP ${response.status} ${response.statusText}`.trim();
+  const description = getStringMember(body, "error_description");
+  return description ? `${status}: ${description}` : status;
+}
+__name(describeUnusableResponse, "describeUnusableResponse");
+function isRetryableStatus(status) {
+  return status >= 500 || status === 429;
+}
+__name(isRetryableStatus, "isRetryableStatus");
+function asDeviceAuthorizationResponse(body) {
+  const deviceCode = getStringMember(body, "device_code");
+  const userCode = getStringMember(body, "user_code");
+  const verificationUri = getStringMember(body, "verification_uri");
+  const expiresIn = getPositiveNumberMember(body, "expires_in");
+  if (!deviceCode || !userCode || !verificationUri || expiresIn === void 0) {
+    return void 0;
+  }
+  return {
+    device_code: deviceCode,
+    user_code: userCode,
+    verification_uri: verificationUri,
+    verification_uri_complete: getStringMember(
+      body,
+      "verification_uri_complete"
+    ),
+    expires_in: expiresIn,
+    interval: getPositiveNumberMember(body, "interval")
+  };
+}
+__name(asDeviceAuthorizationResponse, "asDeviceAuthorizationResponse");
+async function readJson(response, logger) {
+  const text = await response.text();
+  try {
+    return JSON.parse(text);
+  } catch (e) {
+    if (text.match(/<!DOCTYPE html>/)) {
+      logger.debug(
+        "The body of the response was HTML rather than JSON. Check the debug logs to see the full body of the response."
+      );
+      if (text.match(/challenge-platform/)) {
+        logger.debug(
+          `It looks like you might have hit a bot challenge page. This may be transient but if not, please contact Cloudflare to find out what can be done. When you contact Cloudflare, please provide your Ray ID: ${response.headers.get(
+            "cf-ray"
+          )}`
+        );
+      }
+    }
+    logger.debug("Full body of response\n\n", text);
+    throw new Error(
+      `Invalid JSON in response: status: ${response.status} ${response.statusText}`,
+      { cause: e }
+    );
+  }
+}
+__name(readJson, "readJson");
+async function buildDeviceAuthHeaders(logger, isNonInteractiveOrCI2) {
+  const headers = {
+    "Content-Type": "application/x-www-form-urlencoded"
+  };
+  if (await domainUsesAccess(getAuthDomainFromEnv(), logger)) {
+    logger.debug(
+      "Using Cloudflare Access to get an access token for the device authorization request"
+    );
+    Object.assign(
+      headers,
+      await getCloudflareAccessHeaders({ logger, isNonInteractiveOrCI: isNonInteractiveOrCI2 })
+    );
+  }
+  return headers;
+}
+__name(buildDeviceAuthHeaders, "buildDeviceAuthHeaders");
+async function requestDeviceAuthorization(scopes, clientId, logger, isNonInteractiveOrCI2) {
+  const params = new URLSearchParams({
+    client_id: clientId,
+    scope: [...scopes, "offline_access"].join(" ")
+  });
+  const headers = await buildDeviceAuthHeaders(logger, isNonInteractiveOrCI2);
+  const deviceAuthUrl = getDeviceAuthUrl();
+  logger.debug("Fetching device authorization from", deviceAuthUrl);
+  const response = await fetch(deviceAuthUrl, {
+    method: "POST",
+    body: params.toString(),
+    headers
+  });
+  if (!response.ok) {
+    const body2 = await readJson(response, logger).catch(() => void 0);
+    const rawError = body2 && typeof body2 === "object" && "error" in body2 ? String(body2.error) : `HTTP ${response.status} ${response.statusText}`;
+    throw toErrorClass(rawError);
+  }
+  const body = await readJson(response, logger);
+  const deviceAuth = asDeviceAuthorizationResponse(body);
+  if (deviceAuth === void 0) {
+    logger.debug("Unusable device authorization response body:", body);
+    throw new UserError(
+      `The device authorization endpoint returned a response that could not be interpreted (${describeUnusableResponse(response, body)}).
+Enable debug logging to see the full response.`,
+      {
+        telemetryMessage: "user device-flow unusable device authorization response"
+      }
+    );
+  }
+  return deviceAuth;
+}
+__name(requestDeviceAuthorization, "requestDeviceAuthorization");
+async function pollDeviceToken(deviceCode, clientId, logger, isNonInteractiveOrCI2) {
+  const params = new URLSearchParams({
+    grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+    device_code: deviceCode,
+    client_id: clientId
+  });
+  const response = await fetchAuthToken(params, logger, isNonInteractiveOrCI2);
+  const body = await readJson(response, logger);
+  const error = getStringMember(body, "error");
+  if (error !== void 0) {
+    return { kind: "oauth-error", error };
+  }
+  const accessToken = getStringMember(body, "access_token");
+  const expiresIn = getPositiveNumberMember(body, "expires_in");
+  if (!response.ok || accessToken === void 0 || expiresIn === void 0) {
+    logger.debug("Unusable token response body:", body);
+    return {
+      kind: "unexpected",
+      detail: describeUnusableResponse(response, body),
+      // A 2xx that carries no usable grant is not going to become one on the
+      // next attempt, so only the retryable statuses keep the loop alive.
+      retryable: !response.ok && isRetryableStatus(response.status)
+    };
+  }
+  return {
+    kind: "token",
+    grant: {
+      access_token: accessToken,
+      expires_in: expiresIn,
+      refresh_token: getStringMember(body, "refresh_token"),
+      scope: getStringMember(body, "scope")
+    }
+  };
+}
+__name(pollDeviceToken, "pollDeviceToken");
+function sleep(seconds) {
+  return new Promise((resolve) => setTimeout(resolve, seconds * 1e3));
+}
+__name(sleep, "sleep");
+async function getOauthTokenViaDeviceFlow(options, ctx) {
+  const { logger, openInBrowser, isNonInteractiveOrCI: isNonInteractiveOrCI2 } = ctx;
+  const deviceAuth = await requestDeviceAuthorization(
+    options.scopes,
+    options.clientId,
+    logger,
+    isNonInteractiveOrCI2
+  );
+  const authDomain = getAuthDomainFromEnv();
+  assertTrustedVerificationUrl(deviceAuth.verification_uri, {
+    field: "verification_uri",
+    authDomain
+  });
+  if (deviceAuth.verification_uri_complete !== void 0) {
+    assertTrustedVerificationUrl(deviceAuth.verification_uri_complete, {
+      field: "verification_uri_complete",
+      authDomain
+    });
+  }
+  const verificationUrl = deviceAuth.verification_uri_complete ?? generateVerificationUrl({
+    verificationUri: deviceAuth.verification_uri,
+    userCode: deviceAuth.user_code
+  });
+  const maxDurationSeconds = Math.min(
+    deviceAuth.expires_in,
+    DEVICE_FLOW_MAX_DURATION_SECONDS
+  );
+  logger.log(
+    esm_default`
+		To authorize ${ctx.displayName}, please visit:
+
+		  ${deviceAuth.verification_uri}
+
+		and enter the code:
+
+		  ${deviceAuth.user_code}
+
+		You have ${toHumanPeriod(maxDurationSeconds)} to approve this request.
+	`
+  );
+  if (options.browser) {
+    logger.log(`
+Opening a link in your default browser: ${verificationUrl}`);
+    await openInBrowser(verificationUrl);
+  }
+  const deadline = Date.now() + maxDurationSeconds * 1e3;
+  let intervalSeconds = Math.max(
+    deviceAuth.interval ?? DEVICE_FLOW_MIN_POLL_INTERVAL_SECONDS,
+    DEVICE_FLOW_MIN_POLL_INTERVAL_SECONDS
+  );
+  let firstPoll = true;
+  let lastPollFailure;
+  while (Date.now() < deadline) {
+    if (!firstPoll) {
+      await sleep(intervalSeconds);
+    }
+    firstPoll = false;
+    let result;
+    try {
+      result = await pollDeviceToken(
+        deviceAuth.device_code,
+        options.clientId,
+        logger,
+        isNonInteractiveOrCI2
+      );
+    } catch (e) {
+      logger.debug("Ignoring transient error while polling for token:", e);
+      lastPollFailure = e instanceof Error ? e.message : String(e);
+      continue;
+    }
+    if (result.kind === "unexpected") {
+      if (!result.retryable) {
+        throw new UserError(
+          `The token endpoint returned a response that could not be interpreted (${result.detail}).
+Enable debug logging to see the full response.`,
+          { telemetryMessage: "user device-flow unusable token response" }
+        );
+      }
+      logger.debug(
+        "Ignoring transient response while polling for token:",
+        result.detail
+      );
+      lastPollFailure = result.detail;
+      continue;
+    }
+    lastPollFailure = void 0;
+    if (result.kind === "oauth-error") {
+      switch (result.error) {
+        case "authorization_pending":
+          continue;
+        case "slow_down":
+          intervalSeconds += 5;
+          continue;
+        case "access_denied":
+          throw new UserError(
+            `Consent denied. You must grant consent to ${ctx.displayName} in order to login.
+If you don't want to do this consider passing an API token via the \`CLOUDFLARE_API_TOKEN\` environment variable.`,
+            { telemetryMessage: "user device-flow consent denied" }
+          );
+        case "expired_token":
+          throw new UserError(
+            `Device code expired before the request was approved. Please run \`${ctx.deviceLoginCommand}\` again to obtain a new code.`,
+            { telemetryMessage: "user device-flow code expired" }
+          );
+        default:
+          throw toErrorClass(result.error);
+      }
+    }
+    const { grant } = result;
+    const accessToken = {
+      value: grant.access_token,
+      expiry: new Date(Date.now() + grant.expires_in * 1e3).toISOString()
+    };
+    const scopes = grant.scope ? grant.scope.split(" ") : [];
+    return {
+      token: accessToken,
+      scopes,
+      refreshToken: grant.refresh_token ? { value: grant.refresh_token } : void 0
+    };
+  }
+  if (lastPollFailure !== void 0) {
+    throw new UserError(
+      `Gave up waiting for device authorization: the token endpoint kept returning responses that could not be interpreted (last: ${lastPollFailure}).
+Enable debug logging to see the full response, then run \`${ctx.deviceLoginCommand}\` to try again.`,
+      { telemetryMessage: "user device-flow poll failed" }
+    );
+  }
+  throw new UserError(
+    `Device authorization timed out after ${toHumanPeriod(maxDurationSeconds)}. Please run \`${ctx.deviceLoginCommand}\` again to obtain a new code.`,
+    { telemetryMessage: "user device-flow authorization timeout" }
+  );
+}
+__name(getOauthTokenViaDeviceFlow, "getOauthTokenViaDeviceFlow");
+function toHumanPeriod(seconds) {
+  if (seconds < 60) {
+    return `${seconds} seconds`;
+  }
+  const minutes = Math.floor(seconds / 60);
+  const minutesPostfix = minutes === 1 ? "minute" : "minutes";
+  const remainingSeconds = seconds % 60;
+  const secondsPostfix = remainingSeconds === 1 ? "second" : "seconds";
+  if (remainingSeconds === 0) {
+    return `${minutes} ${minutesPostfix}`;
+  }
+  if (remainingSeconds == 59) {
+    return `${minutes + 1} ${minutesPostfix}`;
+  }
+  return `${minutes} ${minutesPostfix} and ${remainingSeconds} ${secondsPostfix}`;
+}
+__name(toHumanPeriod, "toHumanPeriod");
 
 // src/flow.ts
 function createOAuthFlow(ctx) {
@@ -1243,22 +1590,37 @@ function createOAuthFlow(ctx) {
         }
       );
     }
-    ctx.logger.log("Attempting to login via OAuth...");
-    const oauth = await getOauthToken(
-      {
-        browser: props.browser ?? true,
-        scopes: props.scopes,
-        clientId: getClientId(),
-        redirectUri: ctx.redirectUri,
-        denied: consent.denied,
-        granted: consent.granted,
-        callbackHost: props.callbackHost ?? defaultCallbackHost,
-        callbackPort: props.callbackPort ?? defaultCallbackPort
-      },
-      oauthFlowState,
-      ctx,
-      generators
-    );
+    let oauth;
+    if (props.device) {
+      ctx.logger.log(
+        "Attempting to login via OAuth Device Authorization Grant..."
+      );
+      oauth = await getOauthTokenViaDeviceFlow(
+        {
+          browser: props.browser ?? true,
+          scopes: props.scopes,
+          clientId: getClientId()
+        },
+        ctx
+      );
+    } else {
+      ctx.logger.log("Attempting to login via OAuth...");
+      oauth = await getOauthToken(
+        {
+          browser: props.browser ?? true,
+          scopes: props.scopes,
+          clientId: getClientId(),
+          redirectUri: ctx.redirectUri,
+          denied: consent.denied,
+          granted: consent.granted,
+          callbackHost: props.callbackHost ?? defaultCallbackHost,
+          callbackPort: props.callbackPort ?? defaultCallbackPort
+        },
+        oauthFlowState,
+        ctx,
+        generators
+      );
+    }
     getStorage(props.profile).write({
       oauth_token: oauth.token?.value ?? "",
       expiration_time: oauth.token?.expiry,
@@ -3748,4 +4110,4 @@ smol-toml/dist/index.js:
    *)
 */
 
-export { EncryptedFileCredentialStore, FileCredentialStore, LinuxSecretToolKeyProvider, MacSecurityKeyProvider, NapiKeyringKeyProvider, PINNED_KEYRING_VERSION, PKCE_CHARSET, TEMPORARY_TERMS_NOTICE, TEMPORARY_TERMS_PROMPT, clearAccessCaches, clearCredentialStorageState, createCredentialStorageContext, createOAuthFlow, createProfileStore, decryptString, dedent, domainUsesAccess, encryptString, findKeyringBinding, generateAuthUrl, generateKey, generateRandomState, getAccessHeaders, getAuthConfigFilePath, getAuthFromEnv, getAuthUrlFromEnv, getCloudflareAPITokenFromEnv, getCloudflareAccountIdFromEnv, getCloudflareAuthUseKeyringFromEnv, getCloudflareGlobalAuthEmailFromEnv, getCloudflareGlobalAuthKeyFromEnv, getEncryptedAuthConfigFilePath, getKeyringAccountName, getKeyringInstallDir, installKeyringBindingSync, parseEncryptedEnvelope, parseFile, probeSecretTool, readStoredAuthState, resetCredentialStorageState, resolveKeyProvider, scrubEncryptedCredentials, setKeyProviderFactoryForTesting, setKeyringEntryFactory, setLinuxSecretToolRunner, setMacSecurityCommandRunner, setNpmRunner, stringifyFile, validateAccountId, validateProfileName };
+export { EncryptedFileCredentialStore, FileCredentialStore, LinuxSecretToolKeyProvider, MacSecurityKeyProvider, NapiKeyringKeyProvider, PINNED_KEYRING_VERSION, PKCE_CHARSET, TEMPORARY_TERMS_NOTICE, TEMPORARY_TERMS_PROMPT, clearAccessCaches, clearCredentialStorageState, createCredentialStorageContext, createOAuthFlow, createProfileStore, decryptString, dedent, domainUsesAccess, encryptString, findKeyringBinding, generateAuthUrl, generateKey, generateRandomState, generateVerificationUrl, getAccessHeaders, getAuthConfigFilePath, getAuthFromEnv, getAuthUrlFromEnv, getCloudflareAPITokenFromEnv, getCloudflareAccountIdFromEnv, getCloudflareAuthUseKeyringFromEnv, getCloudflareGlobalAuthEmailFromEnv, getCloudflareGlobalAuthKeyFromEnv, getEncryptedAuthConfigFilePath, getKeyringAccountName, getKeyringInstallDir, installKeyringBindingSync, parseEncryptedEnvelope, parseFile, probeSecretTool, readStoredAuthState, resetCredentialStorageState, resolveKeyProvider, scrubEncryptedCredentials, setKeyProviderFactoryForTesting, setKeyringEntryFactory, setLinuxSecretToolRunner, setMacSecurityCommandRunner, setNpmRunner, stringifyFile, validateAccountId, validateProfileName };

package/dist/{chunk-CEH7NWR7.mjs → chunk-AEOSGWMT.mjs}

@@ -1,4 +1,4 @@
-import { stringifyFile, parseFile, dedent, createCredentialStorageContext, createOAuthFlow, getAuthFromEnv, createProfileStore, validateAccountId, getCloudflareAccountIdFromEnv, getAuthConfigFilePath, getEncryptedAuthConfigFilePath, scrubEncryptedCredentials, validateProfileName, getCloudflareAuthUseKeyringFromEnv } from './chunk-7ZPLVMOI.mjs';
+import { stringifyFile, parseFile, dedent, createCredentialStorageContext, createOAuthFlow, getAuthFromEnv, createProfileStore, validateAccountId, getCloudflareAccountIdFromEnv, getAuthConfigFilePath, getEncryptedAuthConfigFilePath, scrubEncryptedCredentials, validateProfileName, getCloudflareAuthUseKeyringFromEnv } from './chunk-7AYQ2BAF.mjs';
 import { __name } from './chunk-O6YSETKJ.mjs';
 import { existsSync, rmSync, mkdirSync, writeFileSync, chmodSync, readFileSync as readFileSync$1, readdirSync } from 'node:fs';
 import path3 from 'node:path';
@@ -810,6 +810,8 @@ Run \`${descriptor.commands.whoami}\` to check your current authentication statu
     purgeOnLoginOrLogout: configCache.purgeConfigCaches,
     clientId: descriptor.clientId,
     consent: descriptor.consent,
+    displayName: descriptor.displayName,
+    deviceLoginCommand: descriptor.commands.deviceLogin,
     redirectUri: descriptor.redirectUri,
     storageFactory: credentialStorage.storageFactory,
     allowGlobalAuthKey,
@@ -855,7 +857,8 @@ Run \`${descriptor.commands.whoami}\` to check your current authentication statu
       browser: props?.browser ?? true,
       callbackHost: props?.callbackHost,
       callbackPort: props?.callbackPort,
-      profile: props?.profile
+      profile: props?.profile,
+      device: props?.device
     };
   }
   __name(withDefaultScopes, "withDefaultScopes");

package/dist/{file-format-B1KgHuUR.d.mts → file-format-Dbmn5hhd.d.mts}

@@ -174,6 +174,18 @@ interface OAuthFlowContext {
      * or denies consent.
      */
     consent: OAuthConsentPages;
+    /**
+     * The consuming CLI's branded name (e.g. `"Wrangler"`, `"cf"`), interpolated
+     * into the copy the flow prints to the user — "To authorize <name>, please
+     * visit ...". Consumer-specific, so it is required.
+     */
+    displayName: string;
+    /**
+     * The command that restarts the device authorization flow (e.g.
+     * `"wrangler login --device"`), quoted when a device code is denied,
+     * expires, or the flow times out. Consumer-specific, so it is required.
+     */
+    deviceLoginCommand: string;
     /**
      * The `redirect_uri` registered on the consumer's OAuth app
      */
@@ -271,6 +283,16 @@ interface LoginProps {
      * Only for use by 'auth create', not exposed to the user
      */
     profile?: string;
+    /**
+     * When `true`, authenticate using the OAuth 2.0 Device Authorization Grant
+     * (RFC 8628) instead of the authorization-code-with-PKCE callback flow. The
+     * device flow does not start a local callback server and works in
+     * environments where the consumer's loopback callback URL
+     * ({@link OAuthFlowContext.redirectUri}) is unreachable from the user's
+     * browser (containers, remote SSH sessions, Codespaces). `callbackHost` and
+     * `callbackPort` are ignored when this is set.
+     */
+    device?: boolean;
 }
 /**
  * Public surface returned by {@link createOAuthFlow}.

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { O as OAuthFlowLogger, U as UserAuthConfig, A as AuthConfigStorage, C as CredentialStore, F as FileFormat } from './file-format-B1KgHuUR.mjs';
-export { a as ConfigStorage, D as DeactivateDirectoryResult, i as DirectoryBindingOperations, j as DirectoryBindingsStorage, L as LoginOrRefreshFailureReason, d as LoginOrRefreshResult, e as LoginProps, b as OAuthFlowContext, P as ProfileConfigOperations, k as ProfileStore, T as TemporaryPreviewAccount, c as createOAuthFlow, h as createProfileStore, g as generateAuthUrl, f as generateRandomState, v as validateProfileName } from './file-format-B1KgHuUR.mjs';
+import { O as OAuthFlowLogger, U as UserAuthConfig, A as AuthConfigStorage, C as CredentialStore, F as FileFormat } from './file-format-Dbmn5hhd.mjs';
+export { a as ConfigStorage, D as DeactivateDirectoryResult, i as DirectoryBindingOperations, j as DirectoryBindingsStorage, L as LoginOrRefreshFailureReason, d as LoginOrRefreshResult, e as LoginProps, b as OAuthFlowContext, P as ProfileConfigOperations, k as ProfileStore, T as TemporaryPreviewAccount, c as createOAuthFlow, h as createProfileStore, g as generateAuthUrl, f as generateRandomState, v as validateProfileName } from './file-format-Dbmn5hhd.mjs';
 import { ApiCredentials } from '@cloudflare/workers-utils';
 import { SpawnSyncReturns } from 'node:child_process';
 
@@ -103,6 +103,25 @@ declare function getCloudflareAccountIdFromEnv(): string | undefined;
  */
 declare const getCloudflareAuthUseKeyringFromEnv: () => boolean | undefined;
 
+/**
+ * Build the URL the user should visit to approve a device authorization
+ * request, with the `user_code` embedded as a query parameter so the user
+ * does not have to type it manually.
+ *
+ * Per RFC 8628 §3.3.1, this is the "verification_uri_complete" optimization
+ * for non-textual transmission (such as QR codes). Authorization servers may
+ * return their own `verification_uri_complete` in the device authorization
+ * response — prefer that when it is provided. Use this helper as a fallback
+ * when only `verification_uri` is available.
+ *
+ * Extracted into its own module (mirroring `generate-auth-url.ts`) so that
+ * tests can mock the generated URL deterministically.
+ */
+declare const generateVerificationUrl: ({ verificationUri, userCode, }: {
+    verificationUri: string;
+    userCode: string;
+}) => string;
+
 declare const TEMPORARY_TERMS_PROMPT: string;
 declare const TEMPORARY_TERMS_NOTICE: string;
 
@@ -790,4 +809,4 @@ declare function decryptString(envelope: EncryptedEnvelope, key: Uint8Array): st
  */
 declare function parseEncryptedEnvelope(raw: unknown): EncryptedEnvelope | undefined;
 
-export { AuthConfigStorage, type CredentialStorageBundle, type CredentialStorageContext, CredentialStore, type EncryptedEnvelope, EncryptedFileCredentialStore, FileCredentialStore, type KeyProvider, type KeyProviderResolution, type KeyringEntry, type KeyringEntryFactory, LinuxSecretToolKeyProvider, type LinuxSecretToolRunner, type MacSecurityCommandRunner, MacSecurityKeyProvider, NapiKeyringKeyProvider, type NpmRunner, OAuthFlowLogger, PINNED_KEYRING_VERSION, PKCE_CHARSET, type ScrubEncryptedCredentialsResult, TEMPORARY_TERMS_NOTICE, TEMPORARY_TERMS_PROMPT, UserAuthConfig, clearAccessCaches, clearCredentialStorageState, createCredentialStorageContext, decryptString, domainUsesAccess, encryptString, findKeyringBinding, generateKey, getAccessHeaders, getAuthConfigFilePath, getAuthFromEnv, getAuthUrlFromEnv, getCloudflareAPITokenFromEnv, getCloudflareAccountIdFromEnv, getCloudflareAuthUseKeyringFromEnv, getCloudflareGlobalAuthEmailFromEnv, getCloudflareGlobalAuthKeyFromEnv, getEncryptedAuthConfigFilePath, getKeyringAccountName, getKeyringInstallDir, installKeyringBindingSync, parseEncryptedEnvelope, probeSecretTool, readStoredAuthState, resetCredentialStorageState, resolveKeyProvider, scrubEncryptedCredentials, setKeyProviderFactoryForTesting, setKeyringEntryFactory, setLinuxSecretToolRunner, setMacSecurityCommandRunner, setNpmRunner };
+export { AuthConfigStorage, type CredentialStorageBundle, type CredentialStorageContext, CredentialStore, type EncryptedEnvelope, EncryptedFileCredentialStore, FileCredentialStore, type KeyProvider, type KeyProviderResolution, type KeyringEntry, type KeyringEntryFactory, LinuxSecretToolKeyProvider, type LinuxSecretToolRunner, type MacSecurityCommandRunner, MacSecurityKeyProvider, NapiKeyringKeyProvider, type NpmRunner, OAuthFlowLogger, PINNED_KEYRING_VERSION, PKCE_CHARSET, type ScrubEncryptedCredentialsResult, TEMPORARY_TERMS_NOTICE, TEMPORARY_TERMS_PROMPT, UserAuthConfig, clearAccessCaches, clearCredentialStorageState, createCredentialStorageContext, decryptString, domainUsesAccess, encryptString, findKeyringBinding, generateKey, generateVerificationUrl, getAccessHeaders, getAuthConfigFilePath, getAuthFromEnv, getAuthUrlFromEnv, getCloudflareAPITokenFromEnv, getCloudflareAccountIdFromEnv, getCloudflareAuthUseKeyringFromEnv, getCloudflareGlobalAuthEmailFromEnv, getCloudflareGlobalAuthKeyFromEnv, getEncryptedAuthConfigFilePath, getKeyringAccountName, getKeyringInstallDir, installKeyringBindingSync, parseEncryptedEnvelope, probeSecretTool, readStoredAuthState, resetCredentialStorageState, resolveKeyProvider, scrubEncryptedCredentials, setKeyProviderFactoryForTesting, setKeyringEntryFactory, setLinuxSecretToolRunner, setMacSecurityCommandRunner, setNpmRunner };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-export { EncryptedFileCredentialStore, FileCredentialStore, LinuxSecretToolKeyProvider, MacSecurityKeyProvider, NapiKeyringKeyProvider, PINNED_KEYRING_VERSION, PKCE_CHARSET, TEMPORARY_TERMS_NOTICE, TEMPORARY_TERMS_PROMPT, clearAccessCaches, clearCredentialStorageState, createCredentialStorageContext, createOAuthFlow, createProfileStore, decryptString, domainUsesAccess, encryptString, findKeyringBinding, generateAuthUrl, generateKey, generateRandomState, getAccessHeaders, getAuthConfigFilePath, getAuthFromEnv, getAuthUrlFromEnv, getCloudflareAPITokenFromEnv, getCloudflareAccountIdFromEnv, getCloudflareAuthUseKeyringFromEnv, getCloudflareGlobalAuthEmailFromEnv, getCloudflareGlobalAuthKeyFromEnv, getEncryptedAuthConfigFilePath, getKeyringAccountName, getKeyringInstallDir, installKeyringBindingSync, parseEncryptedEnvelope, probeSecretTool, readStoredAuthState, resetCredentialStorageState, resolveKeyProvider, scrubEncryptedCredentials, setKeyProviderFactoryForTesting, setKeyringEntryFactory, setLinuxSecretToolRunner, setMacSecurityCommandRunner, setNpmRunner, validateProfileName } from './chunk-7ZPLVMOI.mjs';
+export { EncryptedFileCredentialStore, FileCredentialStore, LinuxSecretToolKeyProvider, MacSecurityKeyProvider, NapiKeyringKeyProvider, PINNED_KEYRING_VERSION, PKCE_CHARSET, TEMPORARY_TERMS_NOTICE, TEMPORARY_TERMS_PROMPT, clearAccessCaches, clearCredentialStorageState, createCredentialStorageContext, createOAuthFlow, createProfileStore, decryptString, domainUsesAccess, encryptString, findKeyringBinding, generateAuthUrl, generateKey, generateRandomState, generateVerificationUrl, getAccessHeaders, getAuthConfigFilePath, getAuthFromEnv, getAuthUrlFromEnv, getCloudflareAPITokenFromEnv, getCloudflareAccountIdFromEnv, getCloudflareAuthUseKeyringFromEnv, getCloudflareGlobalAuthEmailFromEnv, getCloudflareGlobalAuthKeyFromEnv, getEncryptedAuthConfigFilePath, getKeyringAccountName, getKeyringInstallDir, installKeyringBindingSync, parseEncryptedEnvelope, probeSecretTool, readStoredAuthState, resetCredentialStorageState, resolveKeyProvider, scrubEncryptedCredentials, setKeyProviderFactoryForTesting, setKeyringEntryFactory, setLinuxSecretToolRunner, setMacSecurityCommandRunner, setNpmRunner, validateProfileName } from './chunk-7AYQ2BAF.mjs';
 import './chunk-O6YSETKJ.mjs';

package/dist/{keyring-preference-BgjU5DM9.d.mts → keyring-preference-CeP6MLyb.d.mts}

@@ -1,4 +1,4 @@
-import { l as OAuthConsentPages, F as FileFormat, b as OAuthFlowContext, C as CredentialStore, d as LoginOrRefreshResult, U as UserAuthConfig } from './file-format-B1KgHuUR.mjs';
+import { l as OAuthConsentPages, F as FileFormat, b as OAuthFlowContext, C as CredentialStore, d as LoginOrRefreshResult, U as UserAuthConfig } from './file-format-Dbmn5hhd.mjs';
 import { ApiCredentials, ComplianceConfig } from '@cloudflare/workers-utils';
 
 /** Minimal shape of the interactive `select` prompt's options for account selection. */
@@ -42,13 +42,29 @@ interface AuthContext {
  * rather than a fork of the factory.
  */
 interface CliDescriptor {
-    /** CLI name used in user-facing messaging and keyring install-dir scoping (e.g. `"wrangler"`). */
+    /**
+     * The CLI's invocation name, used for keyring install-dir scoping and in
+     * messaging that refers to the executable (e.g. `"wrangler"`, `"cf"`).
+     */
     cliName: string;
+    /**
+     * The CLI's branded name, used in prose addressed to the user (e.g.
+     * `"Wrangler"` for wrangler, `"cf"` for cf). Distinct from
+     * {@link CliDescriptor.cliName}, which names the executable.
+     */
+    displayName: string;
     /** Commands surfaced in auth guidance. */
     commands: {
         login: string;
         whoami: string;
         createProfile: string;
+        /**
+         * The command that restarts the OAuth 2.0 Device Authorization Grant,
+         * surfaced when a device code is denied, expires, or times out. Spelled
+         * out per CLI rather than derived from {@link CliDescriptor.commands.login}
+         * so the flag name stays the CLI's business.
+         */
+        deviceLogin: string;
     };
     /**
      * OS-keyring service identifier. Becomes the `-s` arg to macOS `security`,
@@ -110,6 +126,13 @@ interface CloudflareLoginProps {
     callbackHost?: string;
     callbackPort?: number;
     profile?: string;
+    /**
+     * When `true`, authenticate using the OAuth 2.0 Device Authorization Grant
+     * (RFC 8628) instead of the authorization-code-with-PKCE callback flow. The
+     * device flow does not start a local callback server, so `callbackHost` and
+     * `callbackPort` are ignored when this is set.
+     */
+    device?: boolean;
 }
 /** A Cloudflare CLI's auth layer, returned by {@link createCloudflareAuth}. */
 interface CloudflareAuth {