Merge pull request #277 from contentstack/feat/DX-9341-v2

feat(DX-9341): add oauth support in AM

Author: naman-contentstack

.talismanrc

@@ -18,7 +18,7 @@ fileignoreconfig:
   - filename: packages/contentstack-cli-cm-regex-validate/test/utils/connect-stack.test.ts
     checksum: 018980aa2b919967b9ef9ab1bdf635d4867fe21593fba5890afa443f440228ff
   - filename: packages/contentstack-bulk-operations/src/messages/index.ts
-    checksum: ba38daefd561d9acd018b6ebcb65847eceab6d375b28988d7b5624dcea9ccfe0
+    checksum: c8acefdd18f499a82d839e3cf99e34af9dd464f63f92282739411174ae7b7c37
   - filename: packages/contentstack-bulk-operations/src/utils/operation-flag-matrix.ts
     checksum: 99a3c3eb422a17f73f4c8f15088004fa4c95df3545bdf510310c1f3a20e4c2c2
   - filename: packages/contentstack-bulk-operations/src/base-bulk-command.ts
@@ -43,4 +43,8 @@ fileignoreconfig:
     checksum: cda61a9c90bb39f27c09951b8a2623851296aefd0d3220d066032287a712d899
   - filename: packages/contentstack-asset-management/test/unit/utils/cs-assets-api-adapter.test.ts
     checksum: 63c6bff4d51842d8fa3cce88545259d0a2c3cfe71df95d303d993f692cee883b
+  - filename: packages/contentstack-asset-management/src/utils/cs-assets-api-adapter.ts
+    checksum: bc4a53f96be6a10786e00133245c7bdc43c965c8a98b753e3879e1110cf9c601
+  - filename: packages/contentstack-bulk-operations/test/unit/commands/bulk-assets-cs-assets.test.ts
+    checksum: 1b6b5b0302d3efd9508e2e5d4fe3783da97a110735ca3106ce829cfe93874150
 version: '1.0'

packages/contentstack-asset-management/src/export/assets.ts

@@ -2,12 +2,13 @@ import { resolve as pResolve } from 'node:path';
 import { Readable } from 'node:stream';
 import { mkdir, writeFile } from 'node:fs/promises';
 import chunk from 'lodash/chunk';
-import { configHandler, log, FsUtility } from '@contentstack/cli-utilities';
+import { log, FsUtility } from '@contentstack/cli-utilities';
 
 import type { CSAssetsAPIConfig, LinkedWorkspace } from '../types/cs-assets-api';
 import type { ExportContext } from '../types/export-types';
 import { CSAssetsExportAdapter } from './base';
-import { writeStreamToFile, getArrayFromResponse } from '../utils/export-helpers';
+import { writeStreamToFile, getArrayFromResponse, getSecuredAssetAuth, SecuredAssetAuthError } from '../utils/export-helpers';
+import type { SecuredAssetAuth } from '../utils/export-helpers';
 import { forEachChunkedJsonStore } from '../utils/chunked-json-reader';
 import { withRetry, RetryableHttpError, isRetryableStatus, parseRetryAfterMs } from '../utils/retry';
 import type { CustomPromiseHandler } from '../utils/cs-assets-api-adapter';
@@ -111,7 +112,6 @@ export default class ExportAssets extends CSAssetsExportAdapter {
     await mkdir(filesDir, { recursive: true });
 
     const securedAssets = this.exportContext.securedAssets ?? false;
-    const authtoken = securedAssets ? configHandler.get('authtoken') : null;
     log.debug(
       `Asset downloads: securedAssets=${securedAssets}, concurrency=${this.downloadAssetsBatchConcurrency}, expected=${expectedDownloads}`,
       this.exportContext.context,
@@ -120,6 +120,9 @@ export default class ExportAssets extends CSAssetsExportAdapter {
 
     let downloadOk = 0;
     let downloadFail = 0;
+    // Set when a 401 persists after a forced token refresh — from then on, skip the network
+    // entirely and abort the phase, instead of individually failing every remaining asset.
+    let authFailure: SecuredAssetAuthError | null = null;
 
     await forEachChunkedJsonStore<AssetRecord>(
       assetsDir,
@@ -154,25 +157,60 @@ export default class ExportAssets extends CSAssetsExportAdapter {
       async (records) => {
         const valid = records.filter((asset) => this.isDownloadable(asset));
         if (valid.length === 0) return;
+        const chunkAuthFailure = authFailure;
+        if (chunkAuthFailure) {
+          // Auth already failed hard — count the remaining downloadables without hitting the network.
+          for (const rec of valid) {
+            downloadFail += 1;
+            this.tick(false, `asset: ${rec.filename ?? rec.file_name ?? rec.uid ?? 'asset'}`, chunkAuthFailure.message);
+          }
+          return;
+        }
+        // Resolve per chunk so long download phases pick up proactively refreshed OAuth tokens.
+        let auth: SecuredAssetAuth = securedAssets ? await getSecuredAssetAuth() : {};
         const apiBatches = chunk(valid, this.downloadAssetsBatchConcurrency);
         const promisifyHandler: CustomPromiseHandler = async ({ index, batchIndex }) => {
           const asset = apiBatches[batchIndex][index] as AssetRecord;
           const uid = (asset.uid ?? asset._uid) as string;
           const url = asset.url as string;
           const filename = asset.filename ?? asset.file_name ?? 'asset';
           if (!url || !uid) return;
+          const knownAuthFailure = authFailure as SecuredAssetAuthError | null;
+          if (knownAuthFailure) {
+            downloadFail += 1;
+            this.tick(false, `asset: ${filename}`, knownAuthFailure.message);
+            return;
+          }
           try {
             const separator = url.includes('?') ? '&' : '?';
-            const downloadUrl = securedAssets && authtoken ? `${url}${separator}authtoken=${authtoken}` : url;
+            const doFetch = () =>
+              fetch(
+                securedAssets && auth.authtoken ? `${url}${separator}authtoken=${auth.authtoken}` : url,
+                securedAssets && auth.headers ? { headers: auth.headers } : undefined,
+              );
             // Binary GET is idempotent — retry transient failures with backoff.
             const response = await withRetry(
               async () => {
                 let resp: Response;
                 try {
-                  resp = await fetch(downloadUrl);
+                  resp = await doFetch();
                 } catch (e) {
                   throw new RetryableHttpError(`download network error: ${(e as Error)?.message ?? String(e)}`);
                 }
+                if (securedAssets && resp.status === 401) {
+                  // Token expired or was revoked mid-run — force one refresh (deduped upstream)
+                  // and refetch. A second 401 means auth is unrecoverable: abort the phase.
+                  auth = await getSecuredAssetAuth(true);
+                  try {
+                    resp = await doFetch();
+                  } catch (e) {
+                    throw new RetryableHttpError(`download network error: ${(e as Error)?.message ?? String(e)}`);
+                  }
+                  if (resp.status === 401) {
+                    authFailure = new SecuredAssetAuthError(resp.status);
+                    throw authFailure;
+                  }
+                }
                 if (!resp.ok) {
                   if (isRetryableStatus(resp.status)) {
                     throw new RetryableHttpError(`HTTP ${resp.status}`, resp.status, parseRetryAfterMs(resp.headers.get('retry-after')));
@@ -209,6 +247,16 @@ export default class ExportAssets extends CSAssetsExportAdapter {
       },
     );
 
+    const terminalAuthFailure = authFailure as SecuredAssetAuthError | null;
+    if (terminalAuthFailure) {
+      // Fail the space loudly — a "completed with errors" summary would bury the real cause.
+      log.error(
+        `Aborted asset downloads for space ${spaceUid}: ${terminalAuthFailure.message}`,
+        this.exportContext.context,
+      );
+      throw terminalAuthFailure;
+    }
+
     log.info(
       downloadFail === 0
         ? `Finished downloading ${downloadOk} asset file(s) for space ${spaceUid}`

packages/contentstack-asset-management/src/query-export/cs-assets-query-exporter.ts

@@ -1,15 +1,16 @@
 import { resolve as pResolve } from 'node:path';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { Readable } from 'node:stream';
-import { log, handleAndLogError, configHandler } from '@contentstack/cli-utilities';
+import { log, handleAndLogError } from '@contentstack/cli-utilities';
 
 import type { CsAssetsQueryExportOptions, CSAssetsAPIConfig, LinkedWorkspace } from '../types/cs-assets-api';
 import type { ExportContext } from '../types/export-types';
 import ExportAssetTypes from '../export/asset-types';
 import ExportFields from '../export/fields';
 import { CSAssetsExportAdapter } from '../export/base';
 import chunk from 'lodash/chunk';
-import { getAssetItems, writeStreamToFile } from '../utils/export-helpers';
+import { getAssetItems, writeStreamToFile, getSecuredAssetAuth, SecuredAssetAuthError } from '../utils/export-helpers';
+import type { SecuredAssetAuth } from '../utils/export-helpers';
 import { withRetry, RetryableHttpError, isRetryableStatus, parseRetryAfterMs } from '../utils/retry';
 import type { CustomPromiseHandler } from '../utils/cs-assets-api-adapter';
 
@@ -223,26 +224,64 @@ class QueryExportWorkspaceAdapter extends CSAssetsExportAdapter {
     await mkdir(filesDir, { recursive: true });
 
     const securedAssets = this.exportContext.securedAssets ?? false;
-    const authtoken = securedAssets ? configHandler.get('authtoken') : null;
+    // Set when a 401 persists after a forced token refresh — from then on, skip the network
+    // entirely and abort the phase, instead of individually failing every remaining asset.
+    let authFailure: SecuredAssetAuthError | null = null;
+    // OAuth → Authorization: Bearer header; basic auth → ?authtoken= query param.
+    // Resolved lazily once per sequential batch (handlers within a batch share one resolve), so
+    // long download runs keep picking up proactively refreshed OAuth tokens.
+    let auth: SecuredAssetAuth = {};
+    let authBatchIndex = -1;
+    let authResolve: Promise<void> = Promise.resolve();
+    const ensureAuthForBatch = (batchIndex: number): Promise<void> => {
+      if (!securedAssets) return Promise.resolve();
+      if (batchIndex !== authBatchIndex) {
+        authBatchIndex = batchIndex;
+        authResolve = getSecuredAssetAuth().then((resolved) => {
+          auth = resolved;
+        });
+      }
+      return authResolve;
+    };
 
     const apiBatches = chunk(downloadable, this.downloadAssetsBatchConcurrency);
     const promisifyHandler: CustomPromiseHandler = async ({ index, batchIndex }) => {
       const asset = apiBatches[batchIndex][index];
       const uid = String(asset.uid ?? asset._uid);
       const url = String(asset.url);
       const filename = String(asset.filename ?? asset.file_name ?? 'asset');
+      if (authFailure) return; // auth failed hard — don't hit the network for remaining assets
       try {
+        await ensureAuthForBatch(batchIndex);
         const separator = url.includes('?') ? '&' : '?';
-        const downloadUrl = securedAssets && authtoken ? `${url}${separator}authtoken=${authtoken}` : url;
+        const doFetch = () =>
+          fetch(
+            securedAssets && auth.authtoken ? `${url}${separator}authtoken=${auth.authtoken}` : url,
+            securedAssets && auth.headers ? { headers: auth.headers } : undefined,
+          );
         // Binary GET is idempotent — retry transient failures with backoff.
         const response = await withRetry(
           async () => {
             let resp: Response;
             try {
-              resp = await fetch(downloadUrl);
+              resp = await doFetch();
             } catch (e) {
               throw new RetryableHttpError(`download network error: ${(e as Error)?.message ?? String(e)}`);
             }
+            if (securedAssets && resp.status === 401) {
+              // Token expired or was revoked mid-run — force one refresh (deduped upstream)
+              // and refetch. A second 401 means auth is unrecoverable: abort the phase.
+              auth = await getSecuredAssetAuth(true);
+              try {
+                resp = await doFetch();
+              } catch (e) {
+                throw new RetryableHttpError(`download network error: ${(e as Error)?.message ?? String(e)}`);
+              }
+              if (resp.status === 401) {
+                authFailure = new SecuredAssetAuthError(resp.status);
+                throw authFailure;
+              }
+            }
             if (!resp.ok) {
               if (isRetryableStatus(resp.status)) {
                 throw new RetryableHttpError(`HTTP ${resp.status}`, resp.status, parseRetryAfterMs(resp.headers.get('retry-after')));
@@ -265,5 +304,15 @@ class QueryExportWorkspaceAdapter extends CSAssetsExportAdapter {
     };
 
     await this.makeConcurrentCall({ apiBatches, module: 'asset downloads' }, promisifyHandler);
+
+    const terminalAuthFailure = authFailure as SecuredAssetAuthError | null;
+    if (terminalAuthFailure) {
+      // Fail the space loudly — silently skipping the rest would look like a successful export.
+      log.error(
+        `Aborted asset downloads for space ${spaceUid}: ${terminalAuthFailure.message}`,
+        this.exportContext.context,
+      );
+      throw terminalAuthFailure;
+    }
   }
 }

packages/contentstack-asset-management/src/utils/export-helpers.ts

@@ -1,4 +1,51 @@
 import { createWriteStream } from 'node:fs';
+import { authHandler, authenticationHandler, configHandler } from '@contentstack/cli-utilities';
+
+export interface SecuredAssetAuth {
+  /** OAuth: header to attach to the download fetch (value is already "Bearer <token>"). */
+  headers?: Record<string, string>;
+  /** Basic auth: token to append as ?authtoken= (existing behavior). */
+  authtoken?: string;
+}
+
+/**
+ * Terminal auth failure for secured asset downloads: the server kept rejecting the token even
+ * after a forced refresh. Download loops throw this to abort the whole phase instead of failing
+ * every remaining asset individually.
+ */
+export class SecuredAssetAuthError extends Error {
+  readonly status: number;
+
+  constructor(status: number) {
+    super(
+      `Secured asset download authentication failed (HTTP ${status}) even after refreshing credentials. ` +
+        'Please log in again (csdx auth:login) and re-run the export.',
+    );
+    this.name = 'SecuredAssetAuthError';
+    this.status = status;
+  }
+}
+
+/**
+ * Resolve auth for secured asset binary downloads.
+ * OAuth → Authorization: Bearer header (getAuthDetails handles proactive expiry refresh).
+ * Basic → authtoken query param (existing behavior).
+ *
+ * Pass `forceRefresh` after a 401: the server rejected a token that is still inside its local
+ * expiry window (revoked/invalidated), so force a refresh — concurrent callers are deduped by
+ * authHandler's in-flight refresh promise. No-op for basic auth, which cannot be refreshed.
+ */
+export async function getSecuredAssetAuth(forceRefresh = false): Promise<SecuredAssetAuth> {
+  if (forceRefresh && authenticationHandler.isOauthEnabled) {
+    await authHandler.compareOAuthExpiry(true);
+  }
+  await authenticationHandler.getAuthDetails();
+  if (authenticationHandler.isOauthEnabled) {
+    return { headers: { authorization: authenticationHandler.accessToken } };
+  }
+  const authtoken = configHandler.get('authtoken');
+  return authtoken ? { authtoken } : {};
+}
 
 export function getArrayFromResponse(data: unknown, arrayKey: string): unknown[] {
   if (Array.isArray(data)) return data;

packages/contentstack-asset-management/src/utils/index.ts

@@ -5,8 +5,11 @@ export {
   getArrayFromResponse,
   getAssetItems,
   getReadableStreamFromDownloadResponse,
+  getSecuredAssetAuth,
+  SecuredAssetAuthError,
   writeStreamToFile,
 } from './export-helpers';
+export type { SecuredAssetAuth } from './export-helpers';
 export { chunkArray, runInBatches } from './concurrent-batch';
 export { withRetry, RetryableHttpError, isRetryableStatus, parseRetryAfterMs } from './retry';
 export { detectAssetManagementExportFromContentDir } from './detect-asset-management-export';