Add resumable auth login for non-TTY flows

Allow agents to start Shopify auth without blocking on device-code polling, then resume the stashed device code exchange after the user authorizes.

Author: gonzaloriestra

.changeset/resumable-auth-login.md

@@ -0,0 +1,6 @@
+---
+'@shopify/cli': minor
+'@shopify/cli-kit': minor
+---
+
+Add resumable non-interactive `shopify auth login` with `--resume`.

docs-shopify.dev/commands/interfaces/auth-login.interface.ts

@@ -9,4 +9,10 @@ export interface authlogin {
    * @environment SHOPIFY_FLAG_AUTH_ALIAS
    */
   '--alias <value>'?: string
+
+  /**
+   * Resume a pending non-interactive login flow.
+   * @environment SHOPIFY_FLAG_AUTH_RESUME
+   */
+  '--resume'?: ''
 }

docs-shopify.dev/generated/generated_docs_data_v2.json

@@ -2592,9 +2592,18 @@
           "description": "Alias of the session you want to login to.",
           "isOptional": true,
           "environmentValue": "SHOPIFY_FLAG_AUTH_ALIAS"
+        },
+        {
+          "filePath": "docs-shopify.dev/commands/interfaces/auth-login.interface.ts",
+          "syntaxKind": "PropertySignature",
+          "name": "--resume",
+          "value": "''",
+          "description": "Resume a pending non-interactive login flow.",
+          "isOptional": true,
+          "environmentValue": "SHOPIFY_FLAG_AUTH_RESUME"
         }
       ],
-      "value": "export interface authlogin {\n  /**\n   * Alias of the session you want to login to.\n   * @environment SHOPIFY_FLAG_AUTH_ALIAS\n   */\n  '--alias <value>'?: string\n}"
+      "value": "export interface authlogin {\n  /**\n   * Alias of the session you want to login to.\n   * @environment SHOPIFY_FLAG_AUTH_ALIAS\n   */\n  '--alias <value>'?: string\n\n  /**\n   * Resume a pending non-interactive login flow.\n   * @environment SHOPIFY_FLAG_AUTH_RESUME\n   */\n  '--resume'?: ''\n}"
     }
   },
   "authlogout": {

packages/cli-kit/src/private/node/conf-store.test.ts

@@ -13,6 +13,9 @@ import {
   getCachedPartnerAccountStatus,
   setCachedPartnerAccountStatus,
   runWithRateLimit,
+  clearPendingDeviceAuth,
+  getPendingDeviceAuth,
+  setPendingDeviceAuth,
 } from './conf-store.js'
 import {isLocalEnvironment} from './context/service.js'
 import {LocalStorage} from '../../public/node/local-storage.js'
@@ -194,6 +197,34 @@ describe('removeCurrentSessionId', () => {
   })
 })
 
+describe('pending device auth', () => {
+  test('stores, reads, and clears pending device auth', async () => {
+    await inTemporaryDirectory(async (cwd) => {
+      // Given
+      const config = new LocalStorage<ConfSchema>({cwd})
+      const pendingDeviceAuth = {
+        deviceCode: 'device-code',
+        userCode: 'user-code',
+        verificationUriComplete: 'https://accounts.shopify.com/activate?user_code=user-code',
+        interval: 5,
+        expiresAt: 1893456000000,
+      }
+
+      // When
+      setPendingDeviceAuth(pendingDeviceAuth, config)
+
+      // Then
+      expect(getPendingDeviceAuth(config)).toEqual(pendingDeviceAuth)
+
+      // When
+      clearPendingDeviceAuth(config)
+
+      // Then
+      expect(getPendingDeviceAuth(config)).toBeUndefined()
+    })
+  })
+})
+
 describe('session environment isolation', () => {
   test('getSessions returns production sessions in production', async () => {
     await inTemporaryDirectory(async (cwd) => {

packages/cli-kit/src/private/node/conf-store.ts

@@ -26,13 +26,22 @@ interface Cache {
   [rateLimitKey: RateLimitKey]: CacheValue<number[]>
 }
 
+export interface PendingDeviceAuth {
+  deviceCode: string
+  userCode: string
+  verificationUriComplete: string
+  interval: number
+  expiresAt: number
+}
+
 export interface ConfSchema {
   sessionStore: string
   currentSessionId?: string
   devSessionStore?: string
   currentDevSessionId?: string
   cache?: Cache
   autoUpgradeEnabled?: boolean
+  pendingDeviceAuth?: PendingDeviceAuth
 }
 
 let _instance: LocalStorage<ConfSchema> | undefined
@@ -111,6 +120,31 @@ export function removeCurrentSessionId(config: LocalStorage<ConfSchema> = cliKit
   config.delete(currentSessionIdKey())
 }
 
+/**
+ * Get pending device auth state for a resumable non-interactive login flow.
+ *
+ * @returns Pending device auth state, if present.
+ */
+export function getPendingDeviceAuth(config: LocalStorage<ConfSchema> = cliKitStore()): PendingDeviceAuth | undefined {
+  return config.get('pendingDeviceAuth')
+}
+
+/**
+ * Stash pending device auth state for a later `shopify auth login --resume`.
+ *
+ * @param auth - Pending device auth state.
+ */
+export function setPendingDeviceAuth(auth: PendingDeviceAuth, config: LocalStorage<ConfSchema> = cliKitStore()): void {
+  config.set('pendingDeviceAuth', auth)
+}
+
+/**
+ * Clear pending device auth state after completion or expiry.
+ */
+export function clearPendingDeviceAuth(config: LocalStorage<ConfSchema> = cliKitStore()): void {
+  config.delete('pendingDeviceAuth')
+}
+
 type CacheValueForKey<TKey extends keyof Cache> = NonNullable<Cache[TKey]>['value']
 
 /**

packages/cli-kit/src/private/node/session.ts

@@ -294,8 +294,6 @@ The CLI is currently unable to prompt for reauthentication.`,
  */
 async function executeCompleteFlow(applications: OAuthApplications, existingAlias?: string): Promise<Session> {
   const scopes = getFlattenScopes(applications)
-  const exchangeScopes = getExchangeScopes(applications)
-  const store = applications.adminApi?.storeFqdn
   if (firstPartyDev()) {
     outputDebug(outputContent`Authenticating as Shopify Employee...`)
     scopes.push('employee')
@@ -315,6 +313,28 @@ async function executeCompleteFlow(applications: OAuthApplications, existingAlia
     identityToken = await pollForDeviceAuthorization(deviceAuth.deviceCode, deviceAuth.interval)
   }
 
+  const session = await completeAuthFlow(identityToken, applications, existingAlias)
+  outputCompleted(`Logged in.`)
+  return session
+}
+
+/**
+ * Given an identity token, exchange it for application tokens and build a complete session.
+ * Shared between the interactive login flow and the resumable non-interactive flow.
+ *
+ * @param identityToken - Identity token returned by the OAuth device code flow.
+ * @param applications - Applications to exchange access tokens for.
+ * @param existingAlias - Optional alias from a previous session to preserve if the email fetch fails.
+ * @returns A complete session with identity and application tokens.
+ */
+export async function completeAuthFlow(
+  identityToken: IdentityToken,
+  applications: OAuthApplications,
+  existingAlias?: string,
+): Promise<Session> {
+  const exchangeScopes = getExchangeScopes(applications)
+  const store = applications.adminApi?.storeFqdn
+
   // Exchange identity token for application tokens
   outputDebug(outputContent`CLI token received. Exchanging it for application tokens...`)
   const result = await exchangeAccessForApplicationTokens(identityToken, exchangeScopes, store)
@@ -330,9 +350,6 @@ async function executeCompleteFlow(applications: OAuthApplications, existingAlia
     },
     applications: result,
   }
-
-  outputCompleted(`Logged in.`)
-
   return session
 }
 

packages/cli-kit/src/private/node/session/device-authorization.test.ts

@@ -8,10 +8,11 @@ import {IdentityToken} from './schema.js'
 import {exchangeDeviceCodeForAccessToken} from './exchange.js'
 import {identityFqdn} from '../../../public/node/context/fqdn.js'
 import {shopifyFetch} from '../../../public/node/http.js'
-import {isTTY} from '../../../public/node/ui.js'
+import {isTTY, keypress} from '../../../public/node/ui.js'
 import {err, ok} from '../../../public/node/result.js'
 import {AbortError} from '../../../public/node/error.js'
-import {isCI} from '../../../public/node/system.js'
+import {isCI, openURL} from '../../../public/node/system.js'
+import {mockAndCaptureOutput} from '../../../public/node/testing/output.js'
 
 import {beforeEach, describe, expect, test, vi} from 'vitest'
 import {Response} from 'node-fetch'
@@ -24,6 +25,7 @@ vi.mock('./exchange.js')
 vi.mock('../../../public/node/system.js')
 
 beforeEach(() => {
+  vi.clearAllMocks()
   vi.mocked(isTTY).mockReturnValue(true)
   vi.mocked(isCI).mockReturnValue(false)
 })
@@ -66,6 +68,26 @@ describe('requestDeviceAuthorization', () => {
     expect(got).toEqual(dataExpected)
   })
 
+  test('can request a device auth code without prompting or polling', async () => {
+    // Given
+    const outputMock = mockAndCaptureOutput()
+    const response = new Response(JSON.stringify(data))
+    vi.mocked(shopifyFetch).mockResolvedValue(response)
+    vi.mocked(identityFqdn).mockResolvedValue('fqdn.com')
+    vi.mocked(clientId).mockReturnValue('clientId')
+    vi.mocked(isCI).mockReturnValue(true)
+
+    // When
+    const got = await requestDeviceAuthorization(['scope1', 'scope2'], {noPrompt: true})
+
+    // Then
+    expect(got).toEqual(dataExpected)
+    expect(keypress).not.toHaveBeenCalled()
+    expect(openURL).not.toHaveBeenCalled()
+    expect(outputMock.info()).toContain('User verification code: user_code')
+    expect(outputMock.info()).toContain('verification_uri_complete')
+  })
+
   test('when the response is not valid JSON, throw an error with context', async () => {
     // Given
     const response = new Response('not valid JSON')

packages/cli-kit/src/private/node/session/device-authorization.ts

@@ -28,9 +28,13 @@ export interface DeviceAuthorizationResponse {
  * Also returns a `deviceCode` used for polling the token endpoint in the next step.
  *
  * @param scopes - The scopes to request
+ * @param options - Optional settings for presenting the device authorization instructions.
  * @returns An object with the device authorization response.
  */
-export async function requestDeviceAuthorization(scopes: string[]): Promise<DeviceAuthorizationResponse> {
+export async function requestDeviceAuthorization(
+  scopes: string[],
+  {noPrompt = false}: {noPrompt?: boolean} = {},
+): Promise<DeviceAuthorizationResponse> {
   const fqdn = await identityFqdn()
   const identityClientId = clientId()
   const queryParams = {client_id: identityClientId, scope: scopes.join(' ')}
@@ -69,32 +73,39 @@ export async function requestDeviceAuthorization(scopes: string[]): Promise<Devi
     throw new BugError('Failed to start authorization process')
   }
 
-  outputInfo('\nTo run this command, log in to Shopify.')
-
-  if (isCI()) {
-    throw new AbortError(
-      'Authorization is required to continue, but the current environment does not support interactive prompts.',
-      'To resolve this, specify credentials in your environment, or run the command in an interactive environment such as your local terminal.',
-    )
-  }
-
-  outputInfo(outputContent`User verification code: ${jsonResult.user_code}`)
   const linkToken = outputToken.link(jsonResult.verification_uri_complete)
 
   const cloudMessage = () => {
     outputInfo(outputContent`👉 Open this link to start the auth process: ${linkToken}`)
   }
 
-  if (isCloudEnvironment() || !isTTY()) {
+  if (noPrompt) {
+    outputInfo('\nTo log in to Shopify, open the following URL and enter the verification code.')
+    outputInfo(outputContent`User verification code: ${jsonResult.user_code}`)
     cloudMessage()
   } else {
-    outputInfo('👉 Press any key to open the login page on your browser')
-    await keypress()
-    const opened = await openURL(jsonResult.verification_uri_complete)
-    if (opened) {
-      outputInfo(outputContent`Opened link to start the auth process: ${linkToken}`)
-    } else {
+    outputInfo('\nTo run this command, log in to Shopify.')
+
+    if (isCI()) {
+      throw new AbortError(
+        'Authorization is required to continue, but the current environment does not support interactive prompts.',
+        'To resolve this, specify credentials in your environment, or run the command in an interactive environment such as your local terminal.',
+      )
+    }
+
+    outputInfo(outputContent`User verification code: ${jsonResult.user_code}`)
+
+    if (isCloudEnvironment() || !isTTY()) {
       cloudMessage()
+    } else {
+      outputInfo('👉 Press any key to open the login page on your browser')
+      await keypress()
+      const opened = await openURL(jsonResult.verification_uri_complete)
+      if (opened) {
+        outputInfo(outputContent`Opened link to start the auth process: ${linkToken}`)
+      } else {
+        cloudMessage()
+      }
     }
   }
 

packages/cli-kit/src/public/node/session-auth-status.test.ts

@@ -97,7 +97,7 @@ describe('getAuthStatus', () => {
       identityFqdn: 'accounts.shopify.com',
       agentGuidance: {
         instruction:
-          'No usable Shopify CLI session is available. Run `shopify auth login`, show the verification URL and user code to the user, and keep the command running until authentication completes.',
+          'No usable Shopify CLI session is available. Run `shopify auth login`, show the verification URL and user code to the user, and then run `shopify auth login --resume` after the user authorizes.',
         nextCommand: 'shopify auth login',
       },
     })