transloadit 4.11.1 → 4.13.0

package/src/cli/commands/image.ts

@@ -0,0 +1,282 @@
+import { lstat, mkdir, open, rm } from 'node:fs/promises'
+import { dirname, isAbsolute, relative, resolve } from 'node:path'
+
+import { validateStoragePathPrefix } from '@transloadit/utils'
+import { Command, Option } from 'clipanion'
+import { z } from 'zod'
+
+import { noticeCliCredentialSource, resolveCliConfig } from '../helpers.ts'
+import { resolveStorageWorkspace } from '../storageCatalog.ts'
+import { storagePublicError } from '../storagePublic.ts'
+import {
+  assertStorageCatalogOrigin,
+  defaultStorageCatalog,
+  readStorageCatalog,
+  storageCatalogDelivery,
+  storageTypesPath,
+  updateStorageReceipts,
+} from '../storageReceipts.ts'
+import { nextAppRoot, storageImageEnvBlock, storageImagePage } from '../storageSnippets.ts'
+import { ensureError, isErrnoException } from '../types.ts'
+import { UnauthenticatedCommand } from './BaseCommand.ts'
+
+/** Scaffolds the Node-runtime Next.js integration without overwriting code or env files. */
+export class ImageInitCommand extends UnauthenticatedCommand {
+  static override paths = [['image', 'init']]
+  static override usage = Command.Usage({
+    category: 'Storage',
+    description: 'Optionally scaffold a Storage image example or private authorizer',
+    examples: [['Scaffold an example', 'transloadit image init website/ --example']],
+  })
+
+  privateDelivery = Option.Boolean('--private', false, {
+    description: 'Also generate a redirect route; denies access until you supply authorization',
+  })
+  example = Option.Boolean('--example', false, {
+    description: 'Generate an example page; explicit factories remain an optional escape hatch',
+  })
+  publicDelivery = Option.Boolean('--public', false, {
+    description: 'Publish this directory on the server and use permanent unsigned image URLs',
+  })
+  receipts = Option.String('--receipts', defaultStorageCatalog, {
+    description: 'Rendering catalog selected by withTransloaditImages',
+  })
+  writeEnv = Option.Boolean('--write-env', false, {
+    description: 'Copy an imported application key to an owner-only .env.local; never overwrite it',
+  })
+  prefix = Option.String({ required: true })
+  workspace = Option.String('--workspace', {
+    description: 'Workspace expected for the selected credentials',
+  })
+
+  protected async run(): Promise<number | undefined> {
+    const created: string[] = []
+    let createdCatalog = false
+    let published: string | undefined
+    try {
+      if (this.privateDelivery && this.publicDelivery)
+        throw new Error('Choose either --private or --public, not both')
+      if (!this.privateDelivery && !this.publicDelivery && !this.example)
+        throw new Error('Choose --example or --private; normal uploads need only storage store')
+      const prefix =
+        this.prefix.endsWith('/') || this.prefix === '' ? this.prefix : `${this.prefix}/`
+      try {
+        validateStoragePathPrefix(prefix, 0, 'prefix')
+        if (prefix === '') throw new Error('Image scaffolds must name a directory')
+      } catch (error) {
+        throw new Error(
+          'Provide one safe relative directory prefix ending in /, for example website/',
+          { cause: error },
+        )
+      }
+      const root = nextAppRoot()
+      if (root === undefined)
+        throw new Error('Run image init in a Next.js project containing app/ or src/app/')
+      const catalogArgument = relative(process.cwd(), resolve(this.receipts)).replaceAll('\\', '/')
+      if (
+        catalogArgument === '..' ||
+        catalogArgument.startsWith('../') ||
+        isAbsolute(catalogArgument)
+      )
+        throw new Error(
+          `Catalog ${JSON.stringify(this.receipts)} is outside this Next.js app. Move it inside the app for package-import scaffolding, or use an explicit createImages factory for a shared external catalog. Nothing was written or published.`,
+        )
+      const catalog = await readStorageCatalog(this.receipts)
+      const needsCredentials =
+        this.publicDelivery || catalog === undefined || (this.writeEnv && this.privateDelivery)
+      let environment: string | undefined
+      const saved = resolveCliConfig('login')
+      if (needsCredentials && saved.loadError !== undefined) throw new Error(saved.loadError)
+      const login = saved.auth === undefined ? resolveCliConfig() : saved
+      if (needsCredentials && !this.setupClient(login)) return 1
+      if (needsCredentials) noticeCliCredentialSource(login, this.output)
+      const selectedEndpoint = this.endpoint ?? (catalog === undefined ? login.endpoint : undefined)
+      const deliveryEndpoint =
+        selectedEndpoint === undefined ||
+        new URL(selectedEndpoint).origin === 'https://api2.transloadit.com'
+          ? undefined
+          : selectedEndpoint
+      if (this.writeEnv && this.privateDelivery) {
+        if (saved.credentialsLoginMethod === 'device')
+          throw new Error(
+            'Use a separate application key for private rendering. The device-login key is revoked by auth logout. Omit --write-env and configure TRANSLOADIT_KEY and TRANSLOADIT_SECRET in your application environment. Nothing was written.',
+          )
+        const value = z
+          .string()
+          .min(1)
+          .max(4096)
+          .regex(/^[^\s][^\r\n\0]*$/)
+          .refine((text) => text.trim() === text)
+        const renderingValues = z.object({ TRANSLOADIT_KEY: value, TRANSLOADIT_SECRET: value })
+        const parsed = renderingValues.safeParse({
+          TRANSLOADIT_KEY: saved.credentials?.authKey,
+          TRANSLOADIT_SECRET: saved.credentials?.authSecret,
+        })
+        if (!parsed.success)
+          throw new Error(
+            'Run transloadit auth login first to save your workspace and Auth Key. Nothing was written.',
+          )
+        // Next expands $ even in quoted dotenv values. Reject delimiters instead of silently
+        // changing an opaque secret; JSON quoting alone is not dotenv/Next escaping.
+        environment = Object.entries(parsed.data)
+          .map(([name, text]) => {
+            if (/["\\]/.test(text))
+              throw new Error(
+                'Rendering values cannot contain double quotes or backslashes; configure these values through the application environment instead',
+              )
+            return `${name}="${text.replaceAll('$', '\\$')}"\n`
+          })
+          .join('')
+      }
+      const pageDirectory = `${root}app/storage-image-example`
+      const example = this.example || this.publicDelivery
+      const files = [
+        ...(example
+          ? [
+              {
+                path: `${pageDirectory}/page.tsx`,
+                content: storageImagePage(
+                  relative(resolve(pageDirectory), resolve(this.receipts)).replaceAll('\\', '/'),
+                  prefix,
+                  catalogArgument === defaultStorageCatalog ? undefined : catalogArgument,
+                ),
+              },
+            ]
+          : []),
+        ...(this.privateDelivery
+          ? [
+              {
+                path: 'transloadit.authorize.ts',
+                content: [
+                  "import type { AuthorizeTransloaditImage } from '@transloadit/viewer/next/server'",
+                  '',
+                  '// Replace with your session and per-object authorization for workspace, template and path.',
+                  'export const authorize: AuthorizeTransloaditImage = () => false',
+                  '',
+                ].join('\n'),
+              },
+              {
+                path: `${root}app/api/storage-images/route.ts`,
+                content: "export { GET, HEAD } from '@transloadit/viewer/next/route'\n",
+              },
+            ]
+          : []),
+        ...(environment === undefined ? [] : [{ path: '.env.local', content: environment }]),
+      ]
+      // Discover conflicts before changing server policy; exclusive creates still protect races.
+      for (const file of files) {
+        const existing = await lstat(file.path).catch((error: unknown) => {
+          if (isErrnoException(error) && error.code === 'ENOENT') return undefined
+          throw error
+        })
+        if (existing !== undefined)
+          throw new Error(
+            `Refusing to overwrite ${JSON.stringify(file.path)}. Move or rename it before rerunning image init; existing files were left unchanged.`,
+          )
+      }
+      await updateStorageReceipts(this.receipts, async (previous, signal) => {
+        // Offline example/authorizer scaffolding preserves the caller's catalog without reading
+        // remote metadata, publishing, saving credentials or choosing a different API environment.
+        if (needsCredentials || this.endpoint !== undefined)
+          assertStorageCatalogOrigin(
+            previous,
+            new URL(this.endpoint ?? login.endpoint ?? 'https://api2.transloadit.com').origin,
+            this.receipts,
+          )
+        const workspace =
+          !needsCredentials && previous !== undefined
+            ? previous.workspace
+            : await resolveStorageWorkspace(this, login, previous?.workspace, signal)
+        if (this.workspace !== undefined && this.workspace !== workspace)
+          throw new Error(
+            `Project uses ${workspace}, not ${JSON.stringify(this.workspace)}. Nothing was written.`,
+          )
+        if (previous !== undefined && previous.workspace !== workspace)
+          throw new Error(
+            'Use --receipts with a separate catalog when initializing another workspace. Nothing was written.',
+          )
+        if (this.publicDelivery) {
+          this.output.notice(
+            `Publishing ${prefix} recursively: all current and future objects under this prefix will be public.`,
+          )
+          const result = await this.client
+            .publishStoragePrefix(prefix, { signal })
+            .catch((cause: unknown) => {
+              signal.throwIfAborted()
+              throw new Error(storagePublicError(cause, workspace), { cause })
+            })
+          published = result.prefix
+        }
+        return {
+          ...previous,
+          apiOrigin:
+            previous?.apiOrigin ??
+            (needsCredentials || this.endpoint !== undefined
+              ? new URL(this.endpoint ?? login.endpoint ?? 'https://api2.transloadit.com').origin
+              : undefined),
+          workspace,
+          // An absent delivery block means production, not permission to import another login.
+          delivery:
+            this.endpoint === undefined && previous !== undefined
+              ? previous.delivery
+              : storageCatalogDelivery(selectedEndpoint),
+          public: [
+            ...new Set([
+              ...(previous?.public ?? []),
+              ...(published === undefined ? [] : [published]),
+            ]),
+          ],
+          images: previous?.images ?? {},
+        }
+      })
+      // The catalog is shared Storage state: another command may update it after this lock ends.
+      // Never roll it back when unrelated scaffold-file creation fails.
+      createdCatalog = catalog === undefined
+      for (const file of files) {
+        await mkdir(dirname(file.path), { recursive: true })
+        const handle = await open(file.path, 'wx', file.path === '.env.local' ? 0o600 : 0o666)
+        created.push(file.path)
+        try {
+          await handle.writeFile(file.content)
+        } finally {
+          await handle.close()
+        }
+      }
+      const instruction = this.privateDelivery
+        ? 'Connect your application session and per-object authorization for workspace, template and path in transloadit.authorize.ts; the generated handler denies access until then. Use a separate application key with Smart CDN on and smart_cdn:sign; assemblies:write is also accepted, but grants broader Assembly access. Configure it in Console → Credentials.'
+        : this.publicDelivery
+          ? 'The directory is published. Public images use permanent unsigned CDN URLs.'
+          : 'Example created using the existing catalog; no publication policy was changed.'
+      if (deliveryEndpoint !== undefined)
+        this.output.print(
+          `Delivery uses the non-production API ${new URL(deliveryEndpoint).origin}; remove the catalog delivery block for Smart CDN delivery.`,
+          { deliveryEndpoint: new URL(deliveryEndpoint).origin },
+        )
+      const envBlock = storageImageEnvBlock(this.publicDelivery)
+      const plugin = `Enable withTransloaditImages in next.config.ts${catalogArgument === defaultStorageCatalog ? '' : ` with { catalog: ${JSON.stringify(catalogArgument)} }`}.`
+      const filesCreated = [
+        ...(createdCatalog ? [this.receipts, storageTypesPath(this.receipts)] : []),
+        ...created,
+      ]
+      this.output.print(
+        `Created ${filesCreated.join(', ')}\n${instruction}\n${plugin}\n${example ? `Add an image under ${prefix} with storage store and open /storage-image-example. ` : ''}Commit ${this.receipts} and transloadit-images.d.ts.\n${!this.privateDelivery ? 'Public rendering needs no environment variables, locally or on your host.' : this.writeEnv ? 'Rendering values were saved privately; never commit .env.local.' : `Add your rendering values to .env.local:\n${envBlock}`}`,
+        { files: filesCreated, environment: envBlock },
+      )
+      return undefined
+    } catch (error) {
+      if (createdCatalog)
+        this.output.error(
+          `The catalog ${JSON.stringify(this.receipts)} and its declarations were preserved; another Storage command may already be using them.`,
+        )
+      for (const path of created) {
+        await rm(path).catch(() => {
+          this.output.error(`Could not remove partial scaffold file ${path}; remove it manually.`)
+        })
+      }
+      this.output.error(
+        `${ensureError(error).message}${published === undefined ? '' : ` The server prefix ${published} remains public; use storage unpublish deliberately if needed.`}`,
+      )
+      return 1
+    }
+  }
+}

package/src/cli/commands/index.ts

@@ -12,10 +12,25 @@ import {
   AssemblyInstructionsCompileCommand,
   RunCommand,
 } from './assemblies.ts'
-import { SignatureCommand, SmartCdnSignatureCommand, TokenCommand } from './auth.ts'
+import {
+  AuthHelpCommand,
+  SignatureCommand,
+  SmartCdnSignatureCommand,
+  TokenCommand,
+} from './auth.ts'
 import { BillsGetCommand } from './bills.ts'
 import { DocsRobotsGetCommand, DocsRobotsListCommand } from './docs.ts'
+import { ImageInitCommand } from './image.ts'
+import { AuthLoginCommand, AuthLogoutCommand, AuthStatusCommand } from './login.ts'
 import { NotificationsReplayCommand } from './notifications.ts'
+import {
+  StorageListCommand,
+  StoragePublicationsCommand,
+  StoragePublishCommand,
+  StorageReceiptsSyncCommand,
+  StorageStoreCommand,
+  StorageUnpublishCommand,
+} from './storage.ts'
 import {
   TemplatesCreateCommand,
   TemplatesDeleteCommand,
@@ -38,9 +53,13 @@ export function createCli(): Cli {
   cli.register(Builtins.VersionCommand)
 
   // Auth commands (signature generation)
+  cli.register(AuthHelpCommand)
   cli.register(SignatureCommand)
   cli.register(SmartCdnSignatureCommand)
   cli.register(TokenCommand)
+  cli.register(AuthLoginCommand)
+  cli.register(AuthLogoutCommand)
+  cli.register(AuthStatusCommand)
 
   // Assemblies commands
   cli.register(AssembliesCreateCommand)
@@ -66,6 +85,13 @@ export function createCli(): Cli {
 
   // Uploads commands
   cli.register(UploadCommand)
+  cli.register(StorageStoreCommand)
+  cli.register(StorageListCommand)
+  cli.register(StoragePublicationsCommand)
+  cli.register(StoragePublishCommand)
+  cli.register(StorageUnpublishCommand)
+  cli.register(StorageReceiptsSyncCommand)
+  cli.register(ImageInitCommand)
 
   // Prompt-to-Assembly-Instructions commands
   cli.register(AssemblyInstructionsCompileCommand)

package/src/cli/commands/login.ts

@@ -0,0 +1,334 @@
+import type { CliKeySecretCredentials } from '../helpers.ts'
+
+import { randomUUID } from 'node:crypto'
+import { lstat, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises'
+import { basename, dirname } from 'node:path'
+
+import { Command, Option } from 'clipanion'
+import { parse } from 'dotenv'
+import { z } from 'zod'
+
+import { Transloadit } from '../../Transloadit.ts'
+import { deviceLogin } from '../deviceLogin.ts'
+import {
+  cliSignatureAlgorithmSchema,
+  getConfiguredCredentialsFilePath,
+  parseCliLoginSnapshot,
+  readCliInput,
+  resolveCliConfig,
+} from '../helpers.ts'
+import { quoteCredential } from '../secretInput.ts'
+import { ensureError, isErrnoException } from '../types.ts'
+import { UnauthenticatedCommand } from './BaseCommand.ts'
+
+const credentialSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(4096)
+  .regex(/^[^\r\n\0]+$/)
+const credentialsSchema = z.object({
+  TRANSLOADIT_SIGNATURE_ALGORITHM: cliSignatureAlgorithmSchema.optional(),
+  TRANSLOADIT_KEY: credentialSchema,
+  TRANSLOADIT_SECRET: credentialSchema,
+  TRANSLOADIT_WORKSPACE: z
+    .string()
+    .regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/)
+    .optional(),
+})
+
+async function existingLoginMessage(file: string): Promise<string> {
+  const metadata = await lstat(file)
+    .then(async (info) => {
+      if (!info.isFile()) return 'Saved login metadata unavailable (not a regular file).'
+      const fields = parse(await readFile(file, 'utf8'))
+      // Only identity fields are displayed; JSON quoting keeps saved terminal controls inert.
+      return [
+        `Workspace: ${fields.TRANSLOADIT_WORKSPACE ? JSON.stringify(fields.TRANSLOADIT_WORKSPACE) : 'not recorded'}`,
+        `Description: ${fields.TRANSLOADIT_AUTH_KEY_DESCRIPTION ? JSON.stringify(fields.TRANSLOADIT_AUTH_KEY_DESCRIPTION) : 'not recorded'}`,
+        `File modified: ${info.mtime.toISOString()}`,
+      ].join('\n')
+    })
+    .catch(() => 'Saved login metadata unavailable (could not read the file).')
+  return [
+    `Credentials already exist at ${JSON.stringify(file)}. The saved file was preserved.`,
+    metadata,
+    'For a separate login, set TRANSLOADIT_CREDENTIALS_FILE to another file path and run transloadit auth login again.',
+    'Use --replace only if you intend to overwrite this saved login.',
+  ].join('\n')
+}
+
+/** Saves CLI-only credentials without passing secrets through command-line arguments. */
+export class AuthLoginCommand extends UnauthenticatedCommand {
+  static override paths = [['auth', 'login']]
+  static override usage = Command.Usage({
+    category: 'Authentication',
+    description: 'Log in through the browser and save your workspace Auth Key privately',
+    details:
+      'Opens a one-time browser approval; --no-browser prints the URL without opening it. --stdin accepts existing credentials and verifies a signed Template read. Honors a shell TRANSLOADIT_CREDENTIALS_FILE override, never one from project .env, and refuses app env files. Existing credentials require --replace. Uses production unless --endpoint is explicitly supplied.',
+  })
+
+  stdin = Option.Boolean('--stdin', false, {
+    description:
+      'Read TRANSLOADIT_KEY, TRANSLOADIT_SECRET and optional TRANSLOADIT_WORKSPACE in dotenv format; combined Smart CDN keys also need TRANSLOADIT_SIGNATURE_ALGORITHM=sha256',
+  })
+  noBrowser = Option.Boolean('--no-browser', false, {
+    description: 'Print the device approval URL without launching a browser',
+  })
+  replace = Option.Boolean('--replace', false, {
+    description: 'Explicitly replace an existing regular credentials file',
+  })
+
+  protected async run(): Promise<number | undefined> {
+    const file = getConfiguredCredentialsFilePath('shell')
+    const temporary = `${file}.${randomUUID()}.tmp`
+    let ownsTemporary = false
+    let loginWorkspace: string | undefined
+    try {
+      if (/^\.env(?:\.|$)/i.test(basename(file)))
+        throw new Error('Credentials destination must not be an app env file')
+      const info = await lstat(file).catch((error: unknown) => {
+        if (isErrnoException(error) && error.code === 'ENOENT') return undefined
+        throw error
+      })
+      if (info !== undefined) {
+        if (!info.isFile())
+          throw new Error(
+            'Credentials must be a regular file; symlinks and directories are not replaced',
+          )
+        if (!this.replace) throw new Error(await existingLoginMessage(file))
+      }
+      // Never send newly pasted credentials to a project-controlled dotenv endpoint.
+      const endpoint = new URL(this.endpoint ?? 'https://api2.transloadit.com')
+      if (
+        (endpoint.protocol !== 'https:' &&
+          !(
+            endpoint.protocol === 'http:' &&
+            ['localhost', '127.0.0.1', '[::1]'].includes(endpoint.hostname)
+          )) ||
+        endpoint.username ||
+        endpoint.password ||
+        endpoint.search ||
+        endpoint.hash ||
+        endpoint.pathname !== '/'
+      )
+        throw new Error(
+          'Login endpoint must be an HTTPS API origin (HTTP is allowed only on loopback)',
+        )
+      const origin = endpoint.origin
+      let credentials: CliKeySecretCredentials & {
+        workspace?: string
+        authKeyId?: string
+        description?: string
+      }
+      if (this.stdin) {
+        const input = credentialsSchema.safeParse(
+          parse((await readCliInput({ inputPath: '-' })).content ?? ''),
+        )
+        if (!input.success)
+          throw new Error(
+            'Provide a valid TRANSLOADIT_KEY and TRANSLOADIT_SECRET pair; nothing was saved',
+          )
+        credentials = {
+          authKey: input.data.TRANSLOADIT_KEY,
+          authSecret: input.data.TRANSLOADIT_SECRET,
+          workspace: input.data.TRANSLOADIT_WORKSPACE,
+          ...(input.data.TRANSLOADIT_SIGNATURE_ALGORITHM === undefined
+            ? {}
+            : { signatureAlgorithm: input.data.TRANSLOADIT_SIGNATURE_ALGORITHM }),
+        }
+        const client = new Transloadit({
+          ...credentials,
+          endpoint: origin,
+          maxRetries: 0,
+          timeout: 10_000,
+        })
+        await client.listTemplates({ pagesize: 1 }).catch((error: unknown) => {
+          throw new Error(
+            `Could not verify these credentials. Check the endpoint, key/secret and read scope at https://transloadit.com/c/${credentials.workspace ?? '<workspace>'}/template-credentials/. Combined Smart CDN keys need TRANSLOADIT_SIGNATURE_ALGORITHM=sha256 in the stdin input. Nothing was saved.`,
+            { cause: error },
+          )
+        })
+      } else credentials = await deviceLogin(origin, this.output, this.noBrowser)
+      loginWorkspace = credentials.workspace
+      const fields = {
+        TRANSLOADIT_KEY: credentials.authKey,
+        TRANSLOADIT_SECRET: credentials.authSecret,
+        TRANSLOADIT_WORKSPACE: credentials.workspace,
+        TRANSLOADIT_WORKSPACE_VERIFIED: this.stdin ? undefined : 'true',
+        TRANSLOADIT_LOGIN_METHOD: this.stdin ? 'stdin' : 'device',
+        TRANSLOADIT_SIGNATURE_ALGORITHM: credentials.signatureAlgorithm,
+        TRANSLOADIT_ENDPOINT: this.endpoint === undefined ? undefined : origin,
+        TRANSLOADIT_AUTH_KEY_ID: credentials.authKeyId,
+        TRANSLOADIT_AUTH_KEY_DESCRIPTION: credentials.description,
+      }
+      const data = `${Object.entries(fields)
+        .flatMap(([name, value]) =>
+          value === undefined ? [] : [`${name}=${quoteCredential(value)}`],
+        )
+        .join('\n')}\n`
+      await mkdir(dirname(file), { recursive: true, mode: 0o700 })
+      if (this.replace) {
+        const info = await lstat(file).catch((error: unknown) => {
+          if (isErrnoException(error) && error.code === 'ENOENT') return undefined
+          throw error
+        })
+        if (info !== undefined && !info.isFile())
+          throw new Error(
+            'Credentials must be a regular file; symlinks and directories are not replaced',
+          )
+        await writeFile(temporary, data, { flag: 'wx', mode: 0o600 })
+        ownsTemporary = true
+        await rename(temporary, file)
+      } else {
+        await writeFile(file, data, { flag: 'wx', mode: 0o600 })
+      }
+      // A signed read checks dam:write access and catalog readiness without publishing anything.
+      // It does not prove that the worker's object store can accept a later upload.
+      const storagePolicyAccess = await new Transloadit({
+        ...credentials,
+        endpoint: origin,
+        maxRetries: 0,
+        timeout: 10_000,
+      })
+        .listPublicStoragePrefixes()
+        .then(
+          () => true,
+          () => false,
+        )
+      if (!storagePolicyAccess) {
+        const workspace =
+          credentials.workspace !== undefined &&
+          /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/.test(credentials.workspace)
+            ? credentials.workspace
+            : '<workspace>'
+        this.output.warn(
+          `Login saved, but Storage policy access could not be verified. Before uploading, check Storage availability and the Auth Key dam:write scope at https://transloadit.com/c/${workspace}/template-credentials/. A temporary network failure can also prevent this check; retry with transloadit storage publications.`,
+        )
+      }
+      const message =
+        credentials.workspace === undefined
+          ? `Verified one signed Template read and saved CLI credentials to ${file}. Application env files were not changed.`
+          : `Logged in to workspace ${credentials.workspace}`
+      this.output.print(
+        `${message}${storagePolicyAccess ? '\nStorage policy access verified.' : ''}`,
+        {
+          saved: file,
+          storagePolicyAccess,
+          verified: true,
+          ...(credentials.workspace === undefined ? {} : { workspace: credentials.workspace }),
+        },
+      )
+      return undefined
+    } catch (error) {
+      this.output.error(
+        isErrnoException(error) && error.code === 'EEXIST'
+          ? [
+              await existingLoginMessage(file),
+              `This login’s ${this.stdin ? 'verified' : 'approved'} Auth Key was not saved.`,
+              this.stdin
+                ? 'No new Auth Key was created. The supplied key may still be used by other applications.'
+                : `Review it in Console → Credentials: https://transloadit.com/c/${loginWorkspace ?? '<workspace>'}/template-credentials/; revoke it there if no longer needed.`,
+              'Be careful: auth logout would use the saved login, not this unsaved one.',
+            ].join('\n')
+          : ensureError(error).message,
+      )
+      return 1
+    } finally {
+      if (ownsTemporary) await rm(temporary, { force: true })
+    }
+  }
+}
+
+/** Shows the saved CLI login, never a signing key or secret. */
+export class AuthStatusCommand extends UnauthenticatedCommand {
+  static override paths = [['auth', 'status']]
+  static override usage = Command.Usage({
+    category: 'Authentication',
+    description: 'Show the saved CLI workspace and key description',
+  })
+  protected run(): Promise<number | undefined> {
+    const config = resolveCliConfig('login')
+    if (config.credentials === undefined) {
+      this.output.error(config.loadError ?? 'Not logged in. Run transloadit auth login.')
+      return Promise.resolve(1)
+    }
+    const workspace = config.credentialsWorkspace ?? 'not recorded'
+    const description =
+      config.credentialsDescription ?? 'Existing Auth Key (description not recorded)'
+    this.output.print(
+      `Saved login: ${workspace}\n${description}\nStorage commands report any shell or project credential override before use.`,
+      { workspace, description },
+    )
+    return Promise.resolve(undefined)
+  }
+}
+
+/** Revokes browser-login keys; imported application keys need explicit revocation consent. */
+export class AuthLogoutCommand extends UnauthenticatedCommand {
+  static override paths = [['auth', 'logout']]
+  static override usage = Command.Usage({
+    category: 'Authentication',
+    description: 'Remove saved credentials; browser-login keys are also revoked',
+  })
+  revoke = Option.Boolean('--revoke', {
+    description: 'Also revoke an imported Auth Key; other applications using it will stop working',
+  })
+  protected async run(): Promise<number | undefined> {
+    try {
+      if (this.revoke === false)
+        throw new Error(
+          '--no-revoke is not supported. Nothing was changed; browser-login logout revokes its key.',
+        )
+      const file = getConfiguredCredentialsFilePath('shell')
+      if (/^\.env(?:\.|$)/i.test(basename(file)))
+        throw new Error('Logout never removes application env files')
+      const info = await lstat(file)
+      if (!info.isFile())
+        throw new Error('Logout requires a regular credentials file, not a symlink or directory')
+      const before = await readFile(file, 'utf8')
+      // Imported and legacy keys may be shared with applications; never infer disposability.
+      const revoke = this.revoke === true || parse(before).TRANSLOADIT_LOGIN_METHOD === 'device'
+      if (revoke) {
+        const config = parseCliLoginSnapshot(before)
+        if (config.credentials === undefined) throw new Error(config.loadError ?? 'Not logged in')
+        const endpoint = config.credentialsEndpoint ?? 'https://api2.transloadit.com'
+        if (
+          this.endpoint !== undefined &&
+          new URL(this.endpoint).origin !== new URL(endpoint).origin
+        )
+          throw new Error('Logout must use the saved login endpoint; no credentials were sent')
+        await new Transloadit({ ...config.credentials, endpoint, maxRetries: 0, timeout: 10_000 })
+          .revokeOwnAuthKey()
+          .catch((cause: unknown) => {
+            throw new Error(
+              'The CLI key was not revoked. Check connectivity and Console key permissions, then retry; the credentials file was kept.',
+              { cause },
+            )
+          })
+      }
+      if (!(await lstat(file)).isFile() || (await readFile(file, 'utf8')) !== before)
+        throw new Error(
+          `${revoke ? 'The key was revoked, but the' : 'The'} credentials file changed during logout and was preserved`,
+        )
+      await rm(file)
+      this.output.print(
+        revoke
+          ? 'CLI key revoked and saved credentials removed.'
+          : 'Saved credentials removed. Remote credentials were not revoked.',
+        {
+          revoked: revoke,
+          removed: true,
+        },
+      )
+      return undefined
+    } catch (error) {
+      this.output.error(
+        isErrnoException(error) && error.code === 'ENOENT'
+          ? 'Not logged in; no saved credentials file.'
+          : ensureError(error).message,
+      )
+      return 1
+    }
+  }
+}