transloadit 4.11.1 → 4.13.0

package/src/cli/commands/templates.ts

@@ -152,9 +152,11 @@ async function deleteTemplates(
 // Export with `delete` alias for external consumers
 export { deleteTemplates as delete }
 
-const TemplateIdSchema = z.object({
-  id: z.string(),
-})
+const TemplateIdSchema = z
+  .object({
+    id: z.string(),
+  })
+  .passthrough()
 
 const INCLUDE_BUILTIN_VALUES = ['all', 'latest', 'exclusively-all', 'exclusively-latest'] as const
 
@@ -190,11 +192,11 @@ async function list(
       const parsed = TemplateIdSchema.safeParse(item)
       if (!parsed.success) continue
 
-      let template: unknown = item
+      let template = parsed.data
       if (includeContent) {
         try {
           const full = await client.getTemplate(parsed.data.id)
-          template = { ...item, content: full.content }
+          template = { ...template, content: full.content }
         } catch (err) {
           output.error(formatAPIError(err))
         }
@@ -203,8 +205,13 @@ async function list(
       if (fields == null) {
         output.print(parsed.data.id, template)
       } else {
-        const templateRecord = template as Record<string, unknown>
-        output.print(fields.map((field) => templateRecord[field]).join(' '), template)
+        const selected = fields.filter((field) => Object.hasOwn(template, field))
+        output.print(
+          fields
+            .map((field) => (Object.hasOwn(template, field) ? template[field] : undefined))
+            .join(' '),
+          Object.fromEntries(selected.map((field) => [field, template[field]])),
+        )
       }
     }
 

package/src/cli/deviceLogin.ts

@@ -0,0 +1,226 @@
+import type { CliKeySecretCredentials } from './helpers.ts'
+import type { IOutputCtl } from './OutputCtl.ts'
+
+import { hostname } from 'node:os'
+import { setTimeout as delay } from 'node:timers/promises'
+
+import { execa } from 'execa'
+import got from 'got'
+import { z } from 'zod'
+
+import { cliSignatureAlgorithmSchema } from './helpers.ts'
+
+const deviceSchema = z.object({
+  ok: z.literal('CLI_DEVICE_AUTHORIZATION_CREATED'),
+  device_code: z.string().min(1).max(4096),
+  user_code: z
+    .string()
+    .regex(/^[BCDFGHJKLMNPQRSTVWXZ23456789]{4}-[BCDFGHJKLMNPQRSTVWXZ23456789]{4}$/),
+  verification_url: z.string().url(),
+  // The agreed device contract is bounded to 15 minutes; reject incompatible server responses.
+  expires_in: z.number().int().positive().max(900),
+  interval: z.number().int().positive().max(900),
+})
+const authorizedSchema = z.object({
+  ok: z.literal('CLI_DEVICE_AUTHORIZED'),
+  signature_algo: cliSignatureAlgorithmSchema.nullable(),
+  workspace: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/),
+  auth_key: z
+    .string()
+    .min(1)
+    .max(4096)
+    .regex(/^[^\r\n\0]+$/),
+  auth_secret: z
+    .string()
+    .min(1)
+    .max(4096)
+    .regex(/^[^\r\n\0]+$/),
+  auth_key_id: z
+    .string()
+    .regex(/^[a-zA-Z0-9_-]{1,128}$/)
+    .optional(),
+  description: z
+    .string()
+    .max(512)
+    .regex(/^[^\r\n\0]*$/)
+    .optional(),
+})
+const pendingSchema = z.object({
+  ok: z.literal('CLI_DEVICE_AUTHORIZATION_PENDING'),
+  expires_in: z.number().int().nonnegative(),
+})
+const errorSchema = z.object({ error: z.string() })
+const expiredMessage =
+  'Device authorization expired or was already used. Run transloadit auth login again.'
+
+/** Browser-approved credentials; the one-time device code never leaves this module. */
+export interface DeviceLoginCredentials extends CliKeySecretCredentials {
+  workspace: string
+  authKeyId?: string
+  description?: string
+}
+
+/** Obtain a combined Auth Key using the API's single-use device authorization contract. */
+export async function deviceLogin(
+  endpoint: string,
+  output: IOutputCtl,
+  noBrowser: boolean,
+): Promise<DeviceLoginCredentials> {
+  const cancellation = new AbortController()
+  const cancel = (): void => cancellation.abort()
+  process.once('SIGINT', cancel)
+  let expired: AbortSignal | undefined
+  let heartbeat: ReturnType<typeof setInterval> | undefined
+  try {
+    const response = await got
+      .post(`${endpoint}/cli/device_authorizations`, {
+        form: { client: 'transloadit-cli', hostname: hostname() },
+        responseType: 'json',
+        retry: { limit: 0 },
+        followRedirect: false,
+        timeout: { request: 10_000 },
+        signal: cancellation.signal,
+      })
+      .catch((cause: unknown) => {
+        throw new Error(
+          'Could not start browser login. Check the API endpoint and retry; use auth login --stdin for an existing Auth Key.',
+          { cause },
+        )
+      })
+    const parsed = deviceSchema.safeParse(response.body)
+    if (!parsed.success)
+      throw new Error('The API returned an invalid device authorization; nothing was saved')
+    const device = parsed.data
+    const target = new URL(device.verification_url)
+    if (
+      target.username ||
+      target.password ||
+      target.hash ||
+      (target.protocol !== 'https:' &&
+        !(
+          target.protocol === 'http:' &&
+          ['localhost', '127.0.0.1', '[::1]'].includes(target.hostname)
+        ))
+    )
+      throw new Error('The API returned an unsafe verification URL; nothing was opened or saved')
+    expired = AbortSignal.timeout(device.expires_in * 1000)
+    const signal = AbortSignal.any([cancellation.signal, expired])
+    const deadline = performance.now() + device.expires_in * 1000
+    heartbeat = setInterval(() => {
+      const minutes = Math.ceil((deadline - performance.now()) / 60_000)
+      if (signal.aborted || minutes <= 0) return
+      output.notice(
+        `Still waiting for approval, ${minutes} minute${minutes === 1 ? '' : 's'} left. Use the verification URL printed above.`,
+      )
+    }, 60_000)
+    heartbeat.unref()
+    output.print(`Enter code ${device.user_code} at ${target.href}`, {
+      user_code: device.user_code,
+      verification_url: target.href,
+    })
+    const opener =
+      process.platform === 'darwin'
+        ? 'open'
+        : process.platform === 'linux'
+          ? 'xdg-open'
+          : process.platform === 'win32'
+            ? 'cmd'
+            : undefined
+    // On platforms without an opener, the printed URL is the manual approval path.
+    if (!noBrowser && opener !== undefined) {
+      // xdg-open may live as long as the browser; launching it must not delay or cancel polling.
+      // cmd parses metacharacters even with shell:false. A quoted, single-pass env expansion
+      // keeps &, %, and ! in the URL out of command syntax; disable delayed expansion/AutoRun.
+      const browser = execa(
+        opener,
+        opener === 'cmd'
+          ? ['/d', '/v:off', '/c', 'start', '""', '"%TRANSLOADIT_BROWSER_URL%"']
+          : [target.href],
+        {
+          shell: false,
+          ...(opener === 'cmd'
+            ? { windowsVerbatimArguments: true, env: { TRANSLOADIT_BROWSER_URL: target.href } }
+            : {}),
+          stdio: 'ignore',
+          detached: true,
+          cleanup: false,
+        },
+      )
+      browser.unref()
+      void browser.catch(() => {
+        // A wrapper's later failure cannot prove whether its page opened or invalidate login.
+        output.warn(
+          'The browser opener reported an error. If the page did not open, use the verification URL printed above.',
+        )
+      })
+    }
+    let intervalMs = device.interval * 1000
+    while (true) {
+      await delay(intervalMs, undefined, { signal })
+      const token = await got
+        .post(`${endpoint}/cli/device_authorizations/token`, {
+          form: { device_code: device.device_code },
+          responseType: 'json',
+          retry: { limit: 0 },
+          followRedirect: false,
+          throwHttpErrors: false,
+          timeout: { request: 10_000 },
+          signal,
+        })
+        .catch((cause: unknown) => {
+          throw new Error(
+            'Could not finish browser login. Check connectivity and run transloadit auth login again.',
+            { cause },
+          )
+        })
+      const error = errorSchema.safeParse(token.body)
+      if (
+        token.statusCode === 403 &&
+        error.success &&
+        error.data.error === 'CLI_DEVICE_AUTHORIZATION_DENIED'
+      )
+        throw new Error('The login was denied in the browser.')
+      if (token.statusCode === 429 || (error.success && error.data.error === 'slow_down')) {
+        const seconds = Number(token.headers['retry-after'])
+        // Longer waits are pointless after the authorization deadline and can overflow Node's
+        // timer range into 1 ms, accidentally hammering an already rate-limited API.
+        intervalMs = Math.min(
+          device.expires_in * 1000,
+          Math.max(intervalMs + 5000, Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : 0),
+        )
+        continue
+      }
+      if (error.success && error.data.error === 'CLI_DEVICE_AUTHORIZATION_NOT_FOUND')
+        throw new Error(expiredMessage)
+      if (token.statusCode < 200 || token.statusCode >= 300)
+        throw new Error(
+          'Browser login was refused. Run transloadit auth login again; nothing was saved.',
+        )
+      const pending = pendingSchema.safeParse(token.body)
+      if (pending.success) {
+        if (pending.data.expires_in === 0) throw new Error(expiredMessage)
+        continue
+      }
+      const authorized = authorizedSchema.safeParse(token.body)
+      if (!authorized.success)
+        throw new Error('The API returned an invalid login result; nothing was saved')
+      signal.throwIfAborted()
+      return {
+        authKey: authorized.data.auth_key,
+        authSecret: authorized.data.auth_secret,
+        signatureAlgorithm: authorized.data.signature_algo ?? undefined,
+        workspace: authorized.data.workspace,
+        authKeyId: authorized.data.auth_key_id,
+        description: authorized.data.description,
+      }
+    }
+  } catch (cause) {
+    if (cancellation.signal.aborted)
+      throw new Error('Login canceled; nothing was saved.', { cause })
+    if (expired?.aborted) throw new Error(expiredMessage, { cause })
+    throw cause
+  } finally {
+    clearInterval(heartbeat)
+    process.off('SIGINT', cancel)
+  }
+}

package/src/cli/helpers.ts

@@ -1,15 +1,24 @@
 import type { Readable } from 'node:stream'
 
+import type { IOutputCtl } from './OutputCtl.ts'
+
 import fs from 'node:fs'
 import fsp from 'node:fs/promises'
-import { homedir } from 'node:os'
+import { homedir, userInfo } from 'node:os'
 import path from 'node:path'
 
 import { parse as parseDotenv } from 'dotenv'
+import { z } from 'zod'
 
 import { isAPIError } from './types.ts'
 
-export type CliKeySecretCredentials = { authKey: string; authSecret: string }
+/** API signing algorithms supported by CLI credentials and device authorization. */
+export const cliSignatureAlgorithmSchema = z.enum(['sha1', 'sha256', 'sha384', 'sha512'])
+export type CliKeySecretCredentials = {
+  authKey: string
+  authSecret: string
+  signatureAlgorithm?: z.infer<typeof cliSignatureAlgorithmSchema>
+}
 export type CliAuthToken = { authToken: string }
 export type CliAuth = CliKeySecretCredentials | CliAuthToken
 type CliEnvSource = {
@@ -20,7 +29,9 @@ type CliEnvSource = {
 let loadedProjectDotenvPath: string | undefined
 let projectDotenvInjectedValues: Record<string, string> | undefined
 let projectDotenvPreviousValues: Record<string, string | undefined> | undefined
-let shellEnvBeforeProjectDotenv: Record<string, string | undefined> | undefined
+let shellEnvBeforeProjectDotenv:
+  | { values: Record<string, string | undefined>; homeDirectory?: string }
+  | undefined
 
 type LoadCliEnvSourcesResult = {
   loadError?: string
@@ -30,8 +41,17 @@ type LoadCliEnvSourcesResult = {
 
 export type ResolvedCliConfig = {
   auth?: CliAuth
+  authSource?: string
+  authWorkspace?: string
+  authWorkspaceVerified?: boolean
   credentials?: CliKeySecretCredentials
+  credentialsSource?: string
   credentialsEndpoint?: string
+  credentialsWorkspace?: string
+  credentialsWorkspaceVerified?: boolean
+  credentialsAuthKeyId?: string
+  credentialsDescription?: string
+  credentialsLoginMethod?: string
   endpoint?: string
   loadError?: string
 }
@@ -41,13 +61,38 @@ function normalizeEnvValue(value: string | undefined): string | undefined {
   return trimmed ? trimmed : undefined
 }
 
-function getConfiguredCredentialsFilePath(): string {
-  const configuredPath = normalizeEnvValue(process.env.TRANSLOADIT_CREDENTIALS_FILE)
+function credentialHomeDirectory(): string {
+  // Node trusts HOME verbatim; an empty or relative default must never put secrets in a repo.
+  try {
+    const home = homedir()
+    if (path.isAbsolute(home)) return home
+    const fallback = userInfo().homedir
+    if (path.isAbsolute(fallback)) return fallback
+  } catch (error) {
+    throw new Error(
+      'Cannot determine a safe home directory. Set TRANSLOADIT_CREDENTIALS_FILE to an explicit path.',
+      { cause: error },
+    )
+  }
+  throw new Error(
+    'Cannot determine a safe home directory. Set TRANSLOADIT_CREDENTIALS_FILE to an explicit path.',
+  )
+}
+
+/** Login and its env scaffold accept only a shell path override; ordinary reads retain merged lookup. */
+export function getConfiguredCredentialsFilePath(source: 'shell' | 'merged' = 'merged'): string {
+  const values = source === 'shell' ? getShellEnvValues() : process.env
+  const configuredPath = normalizeEnvValue(values.TRANSLOADIT_CREDENTIALS_FILE)
   if (configuredPath != null) {
     return path.resolve(configuredPath)
   }
 
-  return path.join(homedir(), '.transloadit', 'credentials')
+  // HOME/USERPROFILE from project dotenv must not redirect the login's default destination.
+  const shellHome =
+    source === 'shell' && loadedProjectDotenvPath === getProjectDotenvPath()
+      ? shellEnvBeforeProjectDotenv?.homeDirectory
+      : undefined
+  return path.join(shellHome ?? credentialHomeDirectory(), '.transloadit', 'credentials')
 }
 
 function getProjectDotenvPath(): string {
@@ -112,7 +157,15 @@ export function loadProjectDotenvIntoProcessEnv(): string | undefined {
   const projectDotenvPath = getProjectDotenvPath()
   if (loadedProjectDotenvPath !== projectDotenvPath) {
     restoreProjectDotenvFromProcessEnv()
-    shellEnvBeforeProjectDotenv = { ...process.env }
+    shellEnvBeforeProjectDotenv = {
+      values: { ...process.env },
+      // An explicit file makes OS home discovery unnecessary (e.g. an unmapped container UID).
+      // Otherwise capture it before dotenv can replace HOME and redirect a newly saved login.
+      homeDirectory:
+        normalizeEnvValue(process.env.TRANSLOADIT_CREDENTIALS_FILE) == null
+          ? credentialHomeDirectory()
+          : undefined,
+    }
     loadedProjectDotenvPath = projectDotenvPath
   }
 
@@ -144,7 +197,7 @@ export function loadProjectDotenvIntoProcessEnv(): string | undefined {
 
 function getShellEnvValues(): Record<string, string | undefined> {
   if (loadedProjectDotenvPath === getProjectDotenvPath() && shellEnvBeforeProjectDotenv != null) {
-    return shellEnvBeforeProjectDotenv
+    return shellEnvBeforeProjectDotenv.values
   }
 
   return { ...process.env }
@@ -214,12 +267,23 @@ function getSourceValue(source: CliEnvSource, keys: string[]): string | undefine
   return undefined
 }
 
-function getSourceCredentials(source: CliEnvSource): CliKeySecretCredentials | undefined {
+function getSourceCredentials(
+  source: CliEnvSource,
+): CliKeySecretCredentials | { loadError: string } | undefined {
   const authKey = getSourceValue(source, ['TRANSLOADIT_KEY', 'TRANSLOADIT_AUTH_KEY'])
   const authSecret = getSourceValue(source, ['TRANSLOADIT_SECRET', 'TRANSLOADIT_AUTH_SECRET'])
   if (authKey == null || authSecret == null) return undefined
 
-  return { authKey, authSecret }
+  const algorithm = cliSignatureAlgorithmSchema
+    .optional()
+    .safeParse(getSourceValue(source, ['TRANSLOADIT_SIGNATURE_ALGORITHM']))
+  if (!algorithm.success)
+    return { loadError: 'Unsupported TRANSLOADIT_SIGNATURE_ALGORITHM in CLI credentials' }
+  return {
+    authKey,
+    authSecret,
+    ...(algorithm.data === undefined ? {} : { signatureAlgorithm: algorithm.data }),
+  }
 }
 
 function getSourceAuthToken(source: CliEnvSource): CliAuthToken | undefined {
@@ -240,31 +304,127 @@ function resolveEndpointForSource(
   return getSourceValue(source, ['TRANSLOADIT_ENDPOINT'])
 }
 
-export function resolveCliConfig(): ResolvedCliConfig {
+function isSavedLoginSource(source: CliEnvSource): boolean {
+  return (
+    source.name === 'credentialsFile' &&
+    getConfiguredCredentialsFilePath() === getConfiguredCredentialsFilePath('shell')
+  )
+}
+
+function hasVerifiedWorkspace(source: CliEnvSource, shell: CliEnvSource): boolean {
+  // A project-selected file or changed endpoint cannot inherit the login-time ownership proof.
+  return (
+    isSavedLoginSource(source) &&
+    getSourceValue(source, ['TRANSLOADIT_WORKSPACE_VERIFIED']) === 'true' &&
+    resolveEndpointForSource(source, shell) === getSourceValue(source, ['TRANSLOADIT_ENDPOINT'])
+  )
+}
+
+function credentialSourceName(source: CliEnvSource, shell: CliEnvSource, auth: CliAuth): string {
+  if (source.name === 'credentialsFile')
+    return isSavedLoginSource(source) ? 'saved login' : 'project-selected credentials file'
+  const fields =
+    'authToken' in auth
+      ? [['TRANSLOADIT_AUTH_TOKEN']]
+      : [
+          ['TRANSLOADIT_KEY', 'TRANSLOADIT_AUTH_KEY'],
+          ['TRANSLOADIT_SECRET', 'TRANSLOADIT_AUTH_SECRET'],
+        ]
+  const fromShell = fields.filter((aliases) => {
+    const name = aliases.find((name) => normalizeEnvValue(source.values[name]) !== undefined)
+    return (
+      name !== undefined &&
+      normalizeEnvValue(shell.values[name]) === normalizeEnvValue(source.values[name])
+    )
+  }).length
+  if (fromShell === fields.length) return 'shell environment'
+  return fromShell === 0 ? 'project .env' : 'shell environment + project .env'
+}
+
+/** Quotes a value in the CLI's copyable POSIX-shell commands without expanding user input. */
+export function quoteCliArgument(value: string): string {
+  return /^[a-zA-Z0-9_./-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`
+}
+
+/** Names credential overrides without exposing values or claiming verified ownership. */
+export function noticeCliCredentialSource(
+  config: ResolvedCliConfig,
+  output: Pick<IOutputCtl, 'notice'> | undefined,
+  kind: 'auth' | 'credentials' = 'auth',
+): void {
+  const source = kind === 'auth' ? config.authSource : config.credentialsSource
+  if (source === undefined || source === 'saved login') return
+  const workspace = kind === 'auth' ? config.authWorkspace : config.credentialsWorkspace
+  const label =
+    workspace !== undefined && /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/.test(workspace)
+      ? `workspace declared as ${workspace}`
+      : 'workspace not declared'
+  output?.notice(
+    `Credentials: ${source} (${label}). This override takes precedence over the saved login.`,
+  )
+}
+
+/** Resolve one already-read saved credential snapshot, without consulting the environment again. */
+export function parseCliLoginSnapshot(contents: string): ResolvedCliConfig {
+  return resolveLoginSource({ name: 'credentialsFile', values: parseDotenv(contents) })
+}
+
+function resolveLoginSource(source: CliEnvSource): ResolvedCliConfig {
+  const credentials = getSourceCredentials(source)
+  if (credentials !== undefined && 'loadError' in credentials) return credentials
+  const endpoint = getSourceValue(source, ['TRANSLOADIT_ENDPOINT'])
+  return {
+    auth: credentials,
+    authSource: 'saved login',
+    authWorkspace: getSourceValue(source, ['TRANSLOADIT_WORKSPACE']),
+    authWorkspaceVerified: getSourceValue(source, ['TRANSLOADIT_WORKSPACE_VERIFIED']) === 'true',
+    credentials,
+    credentialsSource: 'saved login',
+    credentialsWorkspace: getSourceValue(source, ['TRANSLOADIT_WORKSPACE']),
+    credentialsWorkspaceVerified:
+      getSourceValue(source, ['TRANSLOADIT_WORKSPACE_VERIFIED']) === 'true',
+    credentialsAuthKeyId: getSourceValue(source, ['TRANSLOADIT_AUTH_KEY_ID']),
+    credentialsDescription: getSourceValue(source, ['TRANSLOADIT_AUTH_KEY_DESCRIPTION']),
+    credentialsLoginMethod: getSourceValue(source, ['TRANSLOADIT_LOGIN_METHOD']),
+    credentialsEndpoint: endpoint,
+    endpoint,
+  }
+}
+
+export function resolveCliConfig(source: 'all' | 'login' = 'all'): ResolvedCliConfig {
+  if (source === 'login') {
+    // Keep login's key, workspace, algorithm and endpoint together, independent of project dotenv.
+    const saved = readEnvFile(getConfiguredCredentialsFilePath('shell'))
+    if (!saved?.ok) return saved === null ? {} : { loadError: saved.error }
+    return resolveLoginSource(saved.source)
+  }
   const { loadError, shellEnvSource, sources } = loadCliEnvSources()
   let auth: CliAuth | undefined
   let authSource: CliEnvSource | undefined
   let credentials: CliKeySecretCredentials | undefined
   let credentialsSource: CliEnvSource | undefined
+  let credentialsError: string | undefined
 
   for (const source of sources) {
-    if (auth == null) {
-      const authToken = getSourceAuthToken(source)
-      if (authToken != null) {
-        auth = authToken
-        authSource = source
-      } else {
-        const sourceCredentials = getSourceCredentials(source)
-        if (sourceCredentials != null) {
-          auth = sourceCredentials
-          authSource = source
-        }
-      }
+    if (auth != null && credentials != null) break
+    const authToken = getSourceAuthToken(source)
+    if (auth == null && authToken != null) {
+      auth = authToken
+      authSource = source
+    }
+    const sourceCredentials = getSourceCredentials(source)
+    if (sourceCredentials !== undefined && 'loadError' in sourceCredentials) {
+      // Signing failure must not discard a valid bearer token or silently choose a different key.
+      credentialsError = sourceCredentials.loadError
+      break
+    }
+    if (auth == null && sourceCredentials != null) {
+      auth = sourceCredentials
+      authSource = source
     }
 
     if (credentials != null) continue
 
-    const sourceCredentials = getSourceCredentials(source)
     if (sourceCredentials != null) {
       credentials = sourceCredentials
       credentialsSource = source
@@ -272,15 +432,32 @@ export function resolveCliConfig(): ResolvedCliConfig {
   }
 
   return {
-    ...(auth != null ? { auth } : {}),
+    ...(auth != null && authSource != null
+      ? {
+          auth,
+          authSource: credentialSourceName(authSource, shellEnvSource, auth),
+          authWorkspace: getSourceValue(authSource, ['TRANSLOADIT_WORKSPACE']),
+          authWorkspaceVerified: hasVerifiedWorkspace(authSource, shellEnvSource),
+        }
+      : {}),
     ...(credentials != null ? { credentials } : {}),
     ...(authSource != null
       ? { endpoint: resolveEndpointForSource(authSource, shellEnvSource) }
       : {}),
     ...(credentialsSource != null
-      ? { credentialsEndpoint: resolveEndpointForSource(credentialsSource, shellEnvSource) }
+      ? {
+          credentialsEndpoint: resolveEndpointForSource(credentialsSource, shellEnvSource),
+          credentialsSource:
+            credentials === undefined
+              ? undefined
+              : credentialSourceName(credentialsSource, shellEnvSource, credentials),
+          credentialsWorkspace: getSourceValue(credentialsSource, ['TRANSLOADIT_WORKSPACE']),
+          credentialsWorkspaceVerified: hasVerifiedWorkspace(credentialsSource, shellEnvSource),
+        }
+      : {}),
+    ...(credentialsError != null || loadError != null
+      ? { loadError: credentialsError ?? loadError }
       : {}),
-    ...(loadError != null ? { loadError } : {}),
   }
 }
 

package/src/cli/secretInput.ts

@@ -0,0 +1,12 @@
+import { parse } from 'dotenv'
+
+/** Preserve opaque punctuation and literal escapes when serializing a CLI credential file. */
+export function quoteCredential(value: string): string {
+  for (const quote of ["'", '"', '`']) {
+    const quoted = `${quote}${value}${quote}`
+    if (parse(`value=${quoted}`).value === value) return quoted
+  }
+  throw new Error(
+    'This credential cannot be represented safely in a dotenv file; nothing was saved',
+  )
+}