@aifabrix/builder 2.47.0 → 2.47.1

package/lib/cli/index.js

@@ -31,6 +31,7 @@ const { setupPlatformCommands } = require('./setup-platform');
 const { setupCertificationCommands } = require('./setup-certification-commands');
 const { setupGovernanceCommands } = require('../commands/governance');
 const { setupChannelCommands } = require('../commands/channel');
+const { setupNpmCommands } = require('./setup-npm');
 
 /**
  * Dev, secrets, parameters, and platform commands (keeps setupCommands under statement limit).
@@ -39,6 +40,7 @@ const { setupChannelCommands } = require('../commands/channel');
 function setupDevAndPlatformCommands(program) {
   setupDevCommands(program);
   setupSecretsCommands(program);
+  setupNpmCommands(program);
   setupParametersCommands(program);
   setupPlatformCommands(program);
 }

package/lib/cli/infra-guided-auth.js

@@ -11,7 +11,7 @@
 const chalk = require('chalk');
 const logger = require('../utils/logger');
 const config = require('../core/config');
-const { resolvePlatformControllerUrl } = require('../utils/platform-controller-url');
+const { resolvePlatformControllerUrl, resolveCliPlatformControllerUrl } = require('../utils/platform-controller-url');
 const { withMutedLogger } = require('../utils/with-muted-logger');
 const { formatBlockingError } = require('../utils/cli-test-layout-chalk');
 const { isAuthenticationError } = require('../utils/cli-utils');
@@ -19,29 +19,45 @@ const { resolveControllerUrl, isPlatformAuthValidForController } = require('../u
 
 /**
  * @param {Object} authOpts
- * @returns {Promise<string>}
+ * @returns {Promise<{ apiUrl: string, tokenUrl: string }>}
  */
-async function resolveGuidedAuthControllerUrl(authOpts = {}) {
-  return (
+async function resolveGuidedAuthControllerUrls(authOpts = {}) {
+  const tokenUrl =
     authOpts.platformControllerUrl ||
     (await config.getPlatformControllerUrl()) ||
-    (await resolvePlatformControllerUrl())
-  );
+    (await resolvePlatformControllerUrl());
+  const remoteServer = await config.getRemoteServer();
+  let apiUrl = tokenUrl;
+  if (remoteServer && String(remoteServer).trim()) {
+    apiUrl = await resolveCliPlatformControllerUrl();
+  }
+  return { apiUrl, tokenUrl };
+}
+
+/**
+ * @param {Object} authOpts
+ * @returns {Promise<string>}
+ */
+async function resolveGuidedAuthControllerUrl(authOpts = {}) {
+  const { apiUrl } = await resolveGuidedAuthControllerUrls(authOpts);
+  return apiUrl;
 }
 
 /**
  * @async
  * @param {Function} handleLoginFn
- * @param {string} controllerUrl
- * @param {{ skipDataplaneVersionRefresh?: boolean }} [opts]
+ * @param {string} controllerUrl - Controller API base URL (may be localhost on builder host)
+ * @param {{ skipDataplaneVersionRefresh?: boolean, tokenControllerUrl?: string }} [opts]
  * @returns {Promise<void>}
  */
 async function runGuidedDeviceLogin(handleLoginFn, controllerUrl, opts = {}) {
   await handleLoginFn({
     method: 'device',
     controller: controllerUrl,
+    tokenControllerUrl: opts.tokenControllerUrl,
     environment: 'dev',
     compact: true,
+    skipControllerUrlPersist: Boolean(opts.tokenControllerUrl),
     skipDataplaneVersionRefresh: opts.skipDataplaneVersionRefresh === true,
     exitOnFailure: false
   });
@@ -56,20 +72,27 @@ async function runGuidedDeviceLogin(handleLoginFn, controllerUrl, opts = {}) {
  */
 async function runGuidedAuthStep(handleLoginFn, authOpts, spinners) {
   const spin = spinners.startSpinner('Authenticating...');
-  const controllerUrl = await resolveGuidedAuthControllerUrl(authOpts);
+  const { apiUrl, tokenUrl } = await resolveGuidedAuthControllerUrls(authOpts);
+  const loginOpts = { skipDataplaneVersionRefresh: true, tokenControllerUrl: tokenUrl };
   const skipLogin =
     authOpts.skipLoginIfAuthenticated === true ||
-    (await isPlatformAuthValidForController(controllerUrl));
+    (await isPlatformAuthValidForController(tokenUrl));
   try {
     if (skipLogin) {
       spinners.stopSpinnerSuccess(spin, 'Already authenticated');
       return;
     }
-    await runGuidedDeviceLogin(handleLoginFn, controllerUrl, { skipDataplaneVersionRefresh: true });
+    await runGuidedDeviceLogin(handleLoginFn, apiUrl, loginOpts);
   } catch (authErr) {
     if (spin) spin.fail('Authentication required');
+    const retriable =
+      isAuthenticationError(authErr) ||
+      /device code|authorization_pending|complete sign-in|browser/i.test(String(authErr.message || ''));
+    if (!retriable) {
+      throw authErr;
+    }
     logger.error(formatBlockingError('Authentication required. Complete sign-in in your browser.'));
-    await runGuidedDeviceLogin(handleLoginFn, controllerUrl, { skipDataplaneVersionRefresh: true });
+    await runGuidedDeviceLogin(handleLoginFn, apiUrl, loginOpts);
   }
   spinners.stopSpinnerSuccess(spin, 'Authenticated');
 }
@@ -102,6 +125,7 @@ async function runGuidedDataplaneWithAuthRecovery(options, handleUpDataplane, ha
 }
 
 module.exports = {
+  resolveGuidedAuthControllerUrls,
   resolveGuidedAuthControllerUrl,
   runGuidedDeviceLogin,
   runGuidedAuthStep,

package/lib/cli/setup-npm.js

@@ -0,0 +1,59 @@
+/**
+ * CLI npm command setup (user-global registry auth).
+ *
+ * @fileoverview aifabrix npm config command registration
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+const { handleCommandError } = require('../utils/cli-utils');
+const { handleNpmConfig } = require('../commands/npm-config');
+
+const NPM_CONFIG_HELP_AFTER = `
+Writes @aifabrix scope registry auth to your user npm config (~/.npmrc by default).
+Does not modify repo-level .npmrc files.
+
+Token source (default): merged secrets key BASH_NPM_TOKEN (user or --shared store).
+Docker/build: BASH_NPM_TOKEN is also mapped to NPM_TOKEN for aifabrix build.
+
+Examples:
+  $ aifabrix secret set BASH_NPM_TOKEN "<token>" --shared
+  $ aifabrix npm config
+  $ aifabrix npm config --check
+  $ aifabrix npm config --dry-run
+  $ NPM_TOKEN="<token>" aifabrix npm config --from-env
+
+Migration from repo .npmrc.token:
+  1. aifabrix secret remove npm-token-secretKeyVault --shared
+  2. aifabrix secret set BASH_NPM_TOKEN "<token>" --shared
+  3. aifabrix npm config
+  4. npm whoami --registry=https://registry.npmjs.org/
+`;
+
+/**
+ * @param {import('commander').Command} program
+ */
+function setupNpmCommands(program) {
+  const npm = program.command('npm').description('User-global npm registry configuration');
+
+  npm
+    .command('config')
+    .description('Apply @aifabrix npm auth from BASH_NPM_TOKEN to user ~/.npmrc')
+    .option('--dry-run', 'Show what would be written without changing files')
+    .option('--check', 'Exit 0 when BASH_NPM_TOKEN is set and npm whoami succeeds')
+    .option('--from-env', 'Use NPM_TOKEN from the environment once (not merged secrets)')
+    .addHelpText('after', NPM_CONFIG_HELP_AFTER)
+    .action(async(opts) => {
+      try {
+        await handleNpmConfig({
+          dryRun: Boolean(opts.dryRun),
+          check: Boolean(opts.check),
+          fromEnv: Boolean(opts.fromEnv)
+        });
+      } catch (error) {
+        handleCommandError(error, 'npm config');
+      }
+    });
+}
+
+module.exports = { setupNpmCommands };

package/lib/cli/setup-secrets.js

@@ -101,7 +101,7 @@ Examples:
 const SECRET_SET_SECRETS_FILE_HELP_AFTER = `
 Examples:
   $ aifabrix secret set-secrets-file ./shared-secrets.yaml
-  $ aifabrix secret set-secrets-file https://dev.example.com/api/secrets
+  $ aifabrix secret set-secrets-file https://builder01.local/api/dev/secrets
   $ aifabrix secret set-secrets-file ""
 `;
 

package/lib/commands/login-device.js

@@ -81,8 +81,11 @@ async function saveDeviceLoginConfig(controllerUrl, token, refreshToken, expires
  * @returns {Promise<void>}
  */
 async function saveTokenAndDisplaySuccess(controllerUrl, token, refreshToken, expiresAt, envKey, opts = {}) {
-  await saveDeviceLoginConfig(controllerUrl, token, refreshToken, expiresAt);
-  await setControllerUrl(controllerUrl);
+  const storageUrl = opts.tokenControllerUrl
+    ? String(opts.tokenControllerUrl).trim().replace(/\/+$/, '')
+    : controllerUrl;
+  await saveDeviceLoginConfig(storageUrl, token, refreshToken, expiresAt);
+  await setControllerUrl(storageUrl);
   if (envKey) {
     await setCurrentEnvironment(envKey);
   }
@@ -219,6 +222,8 @@ function convertDeviceCodeResponse(apiResponse) {
     device_code: deviceCodeData.deviceCode || deviceCodeData.device_code,
     user_code: deviceCodeData.userCode || deviceCodeData.user_code,
     verification_uri: deviceCodeData.verificationUri || deviceCodeData.verification_uri,
+    verification_uri_complete:
+      deviceCodeData.verificationUriComplete || deviceCodeData.verification_uri_complete,
     expires_in: deviceCodeData.expiresIn || deviceCodeData.expires_in || 600,
     interval: deviceCodeData.interval || 5
   };
@@ -246,8 +251,11 @@ function logDeviceFlowError(deviceError, opts) {
 }
 
 function printCompactDeviceUrl(deviceCodeResponse) {
+  const visitUrl =
+    deviceCodeResponse.verification_uri_complete ||
+    `${deviceCodeResponse.verification_uri}?user_code=${deviceCodeResponse.user_code}`;
   logger.log('\nOpen browser to authenticate:');
-  logger.log(chalk.yellow(`${deviceCodeResponse.verification_uri}?user_code=${deviceCodeResponse.user_code}\n`));
+  logger.log(chalk.yellow(`${visitUrl}\n`));
 }
 
 /**

package/lib/commands/login.js

@@ -86,8 +86,12 @@ async function normalizeControllerUrl(options) {
     controllerUrl = await resolveControllerUrl();
   }
   controllerUrl = String(controllerUrl).trim().replace(/\/+$/, '');
-  // Save controller URL to config
-  await setControllerUrl(controllerUrl);
+  if (!options.skipControllerUrlPersist) {
+    const persistUrl = options.tokenControllerUrl
+      ? String(options.tokenControllerUrl).trim().replace(/\/+$/, '')
+      : controllerUrl;
+    await setControllerUrl(persistUrl);
+  }
   if (!options.compact) {
     logger.log(chalk.gray(`Controller URL: ${controllerUrl}`));
   }
@@ -158,7 +162,8 @@ async function handleCredentialsLoginFlow(controllerUrl, environment, options) {
 async function handleDeviceCodeLoginFlow(controllerUrl, environment, options) {
   return await handleDeviceCodeLogin(controllerUrl, environment, options.online, options.scope, {
     compact: Boolean(options.compact),
-    exitOnFailure: options.exitOnFailure !== false
+    exitOnFailure: options.exitOnFailure !== false,
+    tokenControllerUrl: options.tokenControllerUrl
   });
 }
 

package/lib/commands/npm-config.js

@@ -0,0 +1,103 @@
+/**
+ * aifabrix npm config — apply user-global npm auth from BASH_NPM_TOKEN.
+ *
+ * @fileoverview npm config command handler
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { execFile } = require('child_process');
+const { promisify } = require('util');
+const chalk = require('chalk');
+const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
+const logger = require('../utils/logger');
+const secretsLoad = require('../core/secrets-load');
+const { collectBashPrefixedEnv } = require('../utils/bash-secret-env');
+const {
+  REGISTRY_URL,
+  getUserNpmrcPath,
+  writeUserNpmrcFromToken
+} = require('../utils/npm-user-config');
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Resolve npm token from merged secrets or --from-env.
+ *
+ * @param {{ fromEnv?: boolean }} options
+ * @returns {Promise<string>}
+ */
+async function resolveNpmToken(options = {}) {
+  if (options.fromEnv) {
+    const fromProcess = (process.env.NPM_TOKEN || '').trim();
+    if (!fromProcess) {
+      throw new Error('NPM_TOKEN is not set in the environment (--from-env)');
+    }
+    return fromProcess;
+  }
+  const secrets = await secretsLoad.loadSecrets();
+  const bashEnv = collectBashPrefixedEnv(secrets);
+  const token = bashEnv.NPM_TOKEN;
+  if (!token) {
+    throw new Error(
+      'BASH_NPM_TOKEN is not set in merged secrets. Run: aifabrix secret set BASH_NPM_TOKEN "<token>" --shared'
+    );
+  }
+  return token;
+}
+
+/**
+ * Run npm whoami against registry.npmjs.org using the given token.
+ *
+ * @param {string} token
+ * @returns {Promise<string>} username
+ */
+async function npmWhoamiWithToken(token) {
+  const { stdout } = await execFileAsync(
+    'npm',
+    ['whoami', `--registry=${REGISTRY_URL}`, `--//registry.npmjs.org/:_authToken=${token}`],
+    { env: { ...process.env }, timeout: 30000 }
+  );
+  return String(stdout).trim();
+}
+
+/**
+ * @param {{ dryRun?: boolean, check?: boolean, fromEnv?: boolean }} options
+ * @returns {Promise<{ ok: boolean, npmrcPath?: string, username?: string, dryRun?: boolean }>}
+ */
+async function handleNpmConfig(options = {}) {
+  const dryRun = Boolean(options.dryRun);
+  const checkOnly = Boolean(options.check);
+  const token = await resolveNpmToken({ fromEnv: Boolean(options.fromEnv) });
+  const npmrcPath = getUserNpmrcPath();
+
+  if (checkOnly) {
+    const username = await npmWhoamiWithToken(token);
+    return { ok: true, npmrcPath, username };
+  }
+
+  const result = writeUserNpmrcFromToken(token, { dryRun, npmrcPath });
+
+  if (dryRun) {
+    logger.log(chalk.blue('Dry run — would update user npm config:'));
+    logger.log(`  path: ${npmrcPath}`);
+    for (const key of result.managedKeys) {
+      const suffix = key.includes('_authToken') ? '=<redacted>' : '';
+      logger.log(`  ${key}${suffix}`);
+    }
+    return { ok: true, npmrcPath, dryRun: true };
+  }
+
+  const username = await npmWhoamiWithToken(token);
+  logger.log(formatSuccessLine(`Updated user npm config: ${npmrcPath}`));
+  logger.log(chalk.gray(`npm whoami: ${username}`));
+  return { ok: true, npmrcPath, username };
+}
+
+module.exports = {
+  resolveNpmToken,
+  npmWhoamiWithToken,
+  handleNpmConfig
+};

package/lib/utils/api.js

@@ -12,6 +12,7 @@
 
 const { parseErrorResponse, formatNetworkError } = require('./api-error-handler');
 const { inferServiceLabelFromUrl } = require('./service-url-label');
+const { fetchWithOptionalDevPlatformTls } = require('./dev-platform-tls');
 const auditLogger = require('../core/audit-logger');
 
 /** Default timeout for HTTP requests (ms). Prevents hanging when the controller is unreachable. 30s allows Azure Web App cold start to complete. */
@@ -350,7 +351,7 @@ async function makeApiCall(url, options = {}) {
   const { fetchOptions, singleRequestTimeoutMs } = prepareFetchOptionsForRequest(options);
 
   try {
-    const response = await fetch(url, fetchOptions);
+    const response = await fetchWithOptionalDevPlatformTls(url, fetchOptions);
     const duration = Date.now() - startTime;
 
     if (!response.ok) {

package/lib/utils/controller-url.js

@@ -145,7 +145,10 @@ async function isControllerHealthReachable(controllerUrl) {
     return false;
   }
   try {
-    const res = await fetch(`${base}/health`, { signal: AbortSignal.timeout(2500) });
+    const { fetchWithOptionalDevPlatformTls } = require('./dev-platform-tls');
+    const res = await fetchWithOptionalDevPlatformTls(`${base}/health`, {
+      signal: AbortSignal.timeout(2500)
+    });
     return res.ok;
   } catch {
     return false;

package/lib/utils/dev-platform-tls.js

@@ -0,0 +1,148 @@
+/**
+ * Dev platform HTTPS: builder-server nginx front door uses TLS while infra `tlsEnabled` may be off.
+ *
+ * @fileoverview Self-signed TLS allowance for remote dev platform URLs
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const https = require('https');
+const config = require('../core/config');
+const { isLocalhostPublicSchemeHostname } = require('./localhost-public-host');
+
+/**
+ * @param {string} url
+ * @returns {boolean}
+ */
+function isHttpsNonLocalhostUrl(url) {
+  try {
+    const u = new URL(url);
+    return u.protocol === 'https:' && !isLocalhostPublicSchemeHostname(u.hostname);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} requestHostname
+ * @param {string} remoteServerUrl
+ * @returns {boolean}
+ */
+function hostnameMatchesRemoteDevPlatform(requestHostname, remoteServerUrl) {
+  let remoteHost = '';
+  try {
+    remoteHost = new URL(remoteServerUrl).hostname.toLowerCase();
+  } catch {
+    return false;
+  }
+  const host = String(requestHostname || '').trim().toLowerCase();
+  if (!host || !remoteHost) {
+    return false;
+  }
+  return host === remoteHost || host.endsWith(`.${remoteHost}`);
+}
+
+/**
+ * True when URL is a remote dev platform HTTPS endpoint (builder-server nginx / Traefik front door).
+ *
+ * @async
+ * @param {string} url
+ * @returns {Promise<boolean>}
+ */
+async function shouldAllowInsecureDevPlatformTls(url) {
+  if (!isHttpsNonLocalhostUrl(url)) {
+    return false;
+  }
+  try {
+    const remote = await config.getRemoteServer();
+    const remoteTrimmed = remote && String(remote).trim();
+    if (!remoteTrimmed) {
+      return false;
+    }
+    const hostname = new URL(url).hostname;
+    return hostnameMatchesRemoteDevPlatform(hostname, remoteTrimmed);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Minimal fetch for self-signed dev platform HTTPS (Node global fetch cannot set rejectUnauthorized).
+ *
+ * @param {string} url
+ * @param {Object} options
+ * @returns {Promise<{ status: number, statusText: string, headers: { get: Function }, text: Function, json: Function }>}
+ */
+function nodeHttpsFetchInsecure(url, options = {}) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(url);
+    const method = String(options.method || 'GET').toUpperCase();
+    const headers = { ...(options.headers || {}) };
+    const body = options.body;
+    const reqOpts = {
+      hostname: u.hostname,
+      port: u.port || 443,
+      path: `${u.pathname}${u.search}`,
+      method,
+      headers,
+      rejectUnauthorized: false
+    };
+
+    const req = https.request(reqOpts, (res) => {
+      const chunks = [];
+      res.on('data', (chunk) => chunks.push(chunk));
+      res.on('end', () => {
+        const raw = Buffer.concat(chunks).toString('utf8');
+        const status = res.statusCode || 0;
+        resolve({
+          ok: status >= 200 && status < 300,
+          status,
+          statusText: res.statusMessage || '',
+          headers: {
+            get: (name) => res.headers[String(name || '').toLowerCase()] || null
+          },
+          text: async() => raw,
+          json: async() => JSON.parse(raw)
+        });
+      });
+    });
+
+    req.on('error', reject);
+    if (options.signal) {
+      const onAbort = () => {
+        req.destroy(new Error('The operation was aborted'));
+      };
+      if (options.signal.aborted) {
+        onAbort();
+        return;
+      }
+      options.signal.addEventListener('abort', onAbort, { once: true });
+    }
+    if (body !== undefined && body !== null) {
+      req.write(typeof body === 'string' ? body : String(body));
+    }
+    req.end();
+  });
+}
+
+/**
+ * @async
+ * @param {string} url
+ * @param {Object} options
+ * @returns {Promise<Response>}
+ */
+async function fetchWithOptionalDevPlatformTls(url, options = {}) {
+  if (await shouldAllowInsecureDevPlatformTls(url)) {
+    return nodeHttpsFetchInsecure(url, options);
+  }
+  return fetch(url, options);
+}
+
+module.exports = {
+  isHttpsNonLocalhostUrl,
+  hostnameMatchesRemoteDevPlatform,
+  shouldAllowInsecureDevPlatformTls,
+  fetchWithOptionalDevPlatformTls
+};

package/lib/utils/health-check-request.js

@@ -0,0 +1,114 @@
+/**
+ * HTTP(S) health probe request helpers.
+ *
+ * @fileoverview Low-level health endpoint HTTP client
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const http = require('http');
+const https = require('https');
+const chalk = require('chalk');
+const logger = require('./logger');
+const { shouldAllowInsecureDevPlatformTls } = require('./dev-platform-tls');
+
+/**
+ * @param {string} data
+ * @param {number} statusCode
+ * @returns {boolean}
+ */
+function parseHealthResponse(data, statusCode) {
+  try {
+    const health = JSON.parse(data);
+    if (health.status === 'UP') {
+      return true;
+    }
+    if (health.status === 'ok') {
+      return health.database === 'connected' || !health.database;
+    }
+    if (health.status === 'healthy') {
+      return true;
+    }
+    if (health.success === true) {
+      return true;
+    }
+    return false;
+  } catch {
+    return statusCode === 200;
+  }
+}
+
+function handleHealthResponse(res, data, debug, resolve) {
+  const isHealthy = parseHealthResponse(data, res.statusCode);
+  if (debug) {
+    const truncatedData = data.length > 200 ? data.substring(0, 200) + '...' : data;
+    logger.log(chalk.gray(`[DEBUG] Response body: ${truncatedData}`));
+    logger.log(chalk.gray(`[DEBUG] Health check result: ${isHealthy ? 'healthy' : 'unhealthy'}`));
+  }
+  resolve(isHealthy);
+}
+
+function doHealthCheckRequest(healthCheckUrl, debug, resolve, reject, allowInsecureTls = false) {
+  try {
+    const urlObj = new URL(healthCheckUrl);
+    const transport = urlObj.protocol === 'https:' ? https : http;
+    const options = {
+      hostname: urlObj.hostname,
+      port: urlObj.port || (urlObj.protocol === 'https:' ? 443 : 80),
+      path: urlObj.pathname + urlObj.search,
+      method: 'GET',
+      ...(allowInsecureTls ? { rejectUnauthorized: false } : {})
+    };
+    if (debug) {
+      logger.log(chalk.gray(`[DEBUG] Health check request: ${healthCheckUrl}`));
+      logger.log(chalk.gray(`[DEBUG] Request options: ${JSON.stringify(options, null, 2)}`));
+    }
+    const timer = { id: null };
+    const req = transport.request(options, (res) => {
+      clearTimeout(timer.id);
+      let data = '';
+      if (debug) {
+        logger.log(chalk.gray(`[DEBUG] Response status code: ${res.statusCode}`));
+        logger.log(chalk.gray(`[DEBUG] Response headers: ${JSON.stringify(res.headers, null, 2)}`));
+      }
+      res.on('data', (chunk) => {
+        data += chunk;
+      });
+      res.on('end', () => handleHealthResponse(res, data, debug, resolve));
+    });
+    timer.id = setTimeout(() => {
+      if (debug) logger.log(chalk.gray('[DEBUG] Health check request timeout after 5 seconds'));
+      req.destroy();
+      resolve(false);
+    }, 5000);
+    req.on('error', (error) => {
+      clearTimeout(timer.id);
+      if (debug) logger.log(chalk.gray(`[DEBUG] Health check request error: ${error.message}`));
+      resolve(false);
+    });
+    req.end();
+  } catch (error) {
+    if (debug) logger.log(chalk.gray(`[DEBUG] Health check exception: ${error.message}`));
+    reject(error);
+  }
+}
+
+/**
+ * @async
+ * @param {string} healthCheckUrl
+ * @param {boolean} [debug=false]
+ * @returns {Promise<boolean>}
+ */
+async function checkHealthEndpoint(healthCheckUrl, debug = false) {
+  const allowInsecureTls = await shouldAllowInsecureDevPlatformTls(healthCheckUrl);
+  return new Promise((resolve, reject) => {
+    doHealthCheckRequest(healthCheckUrl, debug, resolve, reject, allowInsecureTls);
+  });
+}
+
+module.exports = {
+  parseHealthResponse,
+  checkHealthEndpoint
+};

package/lib/utils/health-check-url.js

@@ -92,6 +92,7 @@ async function computeTraefikPublicAppUrl(_appName, _healthCheckPort, appConfig)
   const remoteServer = await coreConfig.getRemoteServer();
   const developerIdRaw = await coreConfig.getDeveloperId();
   const developerIdNum = parseDeveloperIdNum(developerIdRaw);
+  const setupPlatformMode = await coreConfig.getSetupPlatformMode();
 
   // URLs are resolved for the CLI on the host, not from inside a container.
   const profile = 'local';
@@ -107,7 +108,8 @@ async function computeTraefikPublicAppUrl(_appName, _healthCheckPort, appConfig)
     profile,
     listenPort,
     developerIdNum,
-    infraTlsEnabled
+    infraTlsEnabled,
+    setupPlatformMode
   });
 
   return joinUrlPath(publicBase, mountPath);

package/lib/utils/health-check.js

@@ -9,9 +9,8 @@ const { formatSuccessLine } = require('./cli-test-layout-chalk');
  * @version 2.0.0
  */
 
-const http = require('http');
-const https = require('https');
 const net = require('net');
+const { checkHealthEndpoint } = require('./health-check-request');
 const dns = require('dns');
 const chalk = require('chalk');
 const logger = require('./logger');
@@ -192,117 +191,6 @@ async function getContainerPort(appName, debug = false) {
   return 3000;
 }
 
-/**
- * Parses health check response
- * @function parseHealthResponse
- * @param {string} data - Response data
- * @param {number} statusCode - HTTP status code
- * @returns {boolean} True if healthy
- */
-function parseHealthResponse(data, statusCode) {
-  try {
-    const health = JSON.parse(data);
-    if (health.status === 'UP') {
-      return true;
-    }
-    if (health.status === 'ok') {
-      return health.database === 'connected' || !health.database;
-    }
-    if (health.status === 'healthy') {
-      return true;
-    }
-    if (health.success === true) {
-      return true;
-    }
-    return false;
-  } catch (error) {
-    return statusCode === 200;
-  }
-}
-
-function handleHealthResponse(res, data, debug, resolve) {
-  const isHealthy = parseHealthResponse(data, res.statusCode);
-  if (debug) {
-    const truncatedData = data.length > 200 ? data.substring(0, 200) + '...' : data;
-    logger.log(chalk.gray(`[DEBUG] Response body: ${truncatedData}`));
-    logger.log(chalk.gray(`[DEBUG] Health check result: ${isHealthy ? 'healthy' : 'unhealthy'}`));
-  }
-  resolve(isHealthy);
-}
-
-function doHealthCheckRequest(healthCheckUrl, debug, resolve, reject) {
-  try {
-    const urlObj = new URL(healthCheckUrl);
-    const transport = urlObj.protocol === 'https:' ? https : http;
-    const options = {
-      hostname: urlObj.hostname,
-      port: urlObj.port || (urlObj.protocol === 'https:' ? 443 : 80),
-      path: urlObj.pathname + urlObj.search,
-      method: 'GET'
-    };
-    if (debug) {
-      logger.log(chalk.gray(`[DEBUG] Health check request: ${healthCheckUrl}`));
-      logger.log(chalk.gray(`[DEBUG] Request options: ${JSON.stringify(options, null, 2)}`));
-    }
-    const timer = { id: null };
-    const req = transport.request(options, (res) => {
-      clearTimeout(timer.id);
-      let data = '';
-      if (debug) {
-        logger.log(chalk.gray(`[DEBUG] Response status code: ${res.statusCode}`));
-        logger.log(chalk.gray(`[DEBUG] Response headers: ${JSON.stringify(res.headers, null, 2)}`));
-      }
-      res.on('data', (chunk) => {
-        data += chunk;
-      });
-      res.on('end', () => handleHealthResponse(res, data, debug, resolve));
-    });
-    timer.id = setTimeout(() => {
-      if (debug) logger.log(chalk.gray('[DEBUG] Health check request timeout after 5 seconds'));
-      req.destroy();
-      resolve(false);
-    }, 5000);
-    req.on('error', (error) => {
-      clearTimeout(timer.id);
-      if (debug) logger.log(chalk.gray(`[DEBUG] Health check request error: ${error.message}`));
-      resolve(false);
-    });
-    req.end();
-  } catch (error) {
-    if (debug) logger.log(chalk.gray(`[DEBUG] Health check exception: ${error.message}`));
-    reject(error);
-  }
-}
-
-/**
- * Checks health endpoint
- * @async
- * @function checkHealthEndpoint
- * @param {string} healthCheckUrl - Health check URL
- * @param {boolean} [debug=false] - Enable debug logging
- * @returns {Promise<boolean>} True if healthy
- * @throws {Error} If request fails with exception
- */
-async function checkHealthEndpoint(healthCheckUrl, debug = false) {
-  return new Promise((resolve, reject) => {
-    doHealthCheckRequest(healthCheckUrl, debug, resolve, reject);
-  });
-}
-
-/**
- * Waits for application health check to pass
- * Checks HTTP endpoint and waits for healthy response
- *
- * @async
- * @function waitForHealthCheck
- * @param {string} appName - Application name
- * @param {number} timeout - Timeout in seconds (default: 90)
- * @param {number} [port] - Application port (auto-detected if not provided)
- * @param {Object} [config] - Application configuration
- * @param {boolean} [debug=false] - Enable debug logging
- * @returns {Promise<void>} Resolves when health check passes
- * @throws {Error} If health check times out
- */
 /**
  * Determines health check port
  * @async

package/lib/utils/help-builder.js

@@ -121,6 +121,7 @@ const CATEGORIES = [
     commands: [
       { name: 'dev' },
       { name: 'secret' },
+      { name: 'npm', term: 'npm config' },
       { name: 'secure' }
     ]
   }

package/lib/utils/keycloak-realm-ready.js

@@ -31,7 +31,11 @@ async function probeRealmWellKnown(url) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), 8000);
   try {
-    const res = await fetch(url, { method: 'GET', signal: controller.signal });
+    const { fetchWithOptionalDevPlatformTls } = require('./dev-platform-tls');
+    const res = await fetchWithOptionalDevPlatformTls(url, {
+      method: 'GET',
+      signal: controller.signal
+    });
     return res.ok;
   } catch {
     return false;

package/lib/utils/localhost-public-host.js

@@ -0,0 +1,31 @@
+/**
+ * Loopback hostnames always use http for declarative public URLs.
+ *
+ * @fileoverview Localhost hostname detection for public URL scheme
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * @param {string} hostname
+ * @returns {boolean}
+ */
+function isLocalhostPublicSchemeHostname(hostname) {
+  const h = String(hostname || '').trim().toLowerCase();
+  if (!h) {
+    return false;
+  }
+  if (h === 'localhost') {
+    return true;
+  }
+  if (h === '127.0.0.1') {
+    return true;
+  }
+  return h === '::1';
+}
+
+module.exports = {
+  isLocalhostPublicSchemeHostname
+};

package/lib/utils/npm-user-config.js

@@ -0,0 +1,145 @@
+/**
+ * Merge npm user-global auth lines from BASH_NPM_TOKEN / NPM_TOKEN.
+ *
+ * @fileoverview User-level ~/.npmrc auth for @aifabrix scope (not repo .npmrc)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+/**
+ * Keys managed by aifabrix npm config (replaced or removed on each run).
+ * `always-auth` is legacy — npm 11+ warns at userconfig; auth uses scoped registry + _authToken.
+ */
+const MANAGED_KEYS = new Set([
+  '@aifabrix:registry',
+  'always-auth',
+  '//registry.npmjs.org/:_authToken'
+]);
+
+const REGISTRY_URL = 'https://registry.npmjs.org/';
+
+/**
+ * Resolve npm userconfig file path (~/.npmrc by default).
+ *
+ * @returns {string}
+ */
+function getUserNpmrcPath() {
+  const fromEnv = process.env.npm_config_userconfig || process.env.NPM_CONFIG_USERCONFIG;
+  if (fromEnv && typeof fromEnv === 'string' && fromEnv.trim()) {
+    return path.resolve(fromEnv.trim());
+  }
+  return path.join(os.homedir(), '.npmrc');
+}
+
+/**
+ * Parse a single .npmrc line into key/value (ignores comments and blanks).
+ *
+ * @param {string} line
+ * @returns {{ key: string, value: string }|null}
+ */
+function parseNpmrcLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith('#') || trimmed.startsWith(';')) {
+    return null;
+  }
+  const eq = trimmed.indexOf('=');
+  if (eq === -1) {
+    return { key: trimmed, value: '' };
+  }
+  return {
+    key: trimmed.slice(0, eq).trim(),
+    value: trimmed.slice(eq + 1).trim()
+  };
+}
+
+/**
+ * Build managed auth lines for @aifabrix private registry.
+ *
+ * @param {string} token - Bare npm automation token (never logged by callers)
+ * @returns {string[]}
+ */
+function buildManagedLines(token) {
+  return [
+    `@aifabrix:registry=${REGISTRY_URL}`,
+    `//registry.npmjs.org/:_authToken=${token}`
+  ];
+}
+
+/**
+ * Merge managed lines into existing .npmrc content (idempotent).
+ *
+ * @param {string} existingContent
+ * @param {string} token
+ * @returns {string}
+ */
+function mergeNpmrcContent(existingContent, token) {
+  const kept = [];
+  const lines = (existingContent || '').split(/\r?\n/);
+  for (const line of lines) {
+    const parsed = parseNpmrcLine(line);
+    if (parsed && MANAGED_KEYS.has(parsed.key)) {
+      continue;
+    }
+    kept.push(line);
+  }
+  while (kept.length > 0 && kept[kept.length - 1] === '') {
+    kept.pop();
+  }
+  const managed = buildManagedLines(token);
+  if (kept.length > 0) {
+    return `${kept.join('\n')}\n${managed.join('\n')}\n`;
+  }
+  return `${managed.join('\n')}\n`;
+}
+
+/**
+ * Write merged user-global npm auth from token.
+ *
+ * @param {string} token
+ * @param {{ dryRun?: boolean, npmrcPath?: string }} [options]
+ * @returns {{ npmrcPath: string, managedKeys: string[], dryRun: boolean, wrote: boolean }}
+ */
+function writeUserNpmrcFromToken(token, options = {}) {
+  const npmrcPath = options.npmrcPath || getUserNpmrcPath();
+  const dryRun = Boolean(options.dryRun);
+  const managedKeys = [...MANAGED_KEYS];
+  if (!token || !String(token).trim()) {
+    throw new Error('NPM token is required to update user npm config');
+  }
+  const existing = fs.existsSync(npmrcPath) ? fs.readFileSync(npmrcPath, 'utf8') : '';
+  const merged = mergeNpmrcContent(existing, String(token).trim());
+  if (!dryRun) {
+    const dir = path.dirname(npmrcPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(npmrcPath, merged, { mode: 0o600 });
+    try {
+      fs.chmodSync(npmrcPath, 0o600);
+    } catch {
+      // best-effort on platforms that restrict chmod
+    }
+  }
+  return {
+    npmrcPath,
+    managedKeys,
+    dryRun,
+    wrote: !dryRun
+  };
+}
+
+module.exports = {
+  MANAGED_KEYS,
+  REGISTRY_URL,
+  getUserNpmrcPath,
+  parseNpmrcLine,
+  buildManagedLines,
+  mergeNpmrcContent,
+  writeUserNpmrcFromToken
+};

package/lib/utils/platform-controller-url.js

@@ -103,12 +103,12 @@ async function computeAppBaseUrl(appName) {
   const userCfg = await config.getConfig();
   const remoteServer = await config.getRemoteServer();
   const infraTlsEnabled = Boolean(userCfg && userCfg.tlsEnabled);
+  const setupPlatformMode = await config.getSetupPlatformMode();
 
   const fd = variables.frontDoorRouting || null;
   const frontDoorEnabled = Boolean(fd && fd.enabled === true);
   const traefikOn = Boolean(userCfg && userCfg.traefik);
   const pathActive = Boolean(traefikOn && frontDoorEnabled);
-  const setupPlatformMode = await config.getSetupPlatformMode();
 
   const publicBase = computePublicUrlBaseString({
     traefik: traefikOn,
@@ -120,7 +120,8 @@ async function computeAppBaseUrl(appName) {
     profile: 'docker',
     listenPort: basePort,
     developerIdNum,
-    infraTlsEnabled
+    infraTlsEnabled,
+    setupPlatformMode
   });
 
   if (pathActive) {
@@ -148,10 +149,62 @@ async function resolvePlatformControllerUrl() {
   return computeAppBaseUrl(MISO_CONTROLLER_APP);
 }
 
+/**
+ * Direct localhost controller URL (published Docker port + optional front-door mount).
+ * Used when the CLI runs on the builder host but the public Traefik URL is unreachable.
+ *
+ * @async
+ * @param {string} [appName]
+ * @returns {Promise<string>}
+ */
+async function resolveLocalhostPlatformControllerUrl(appName = MISO_CONTROLLER_APP) {
+  const variables = loadAppVariables(appName);
+  const developerIdRaw = await config.getDeveloperId();
+  const developerIdNum =
+    typeof developerIdRaw === 'string' ? parseInt(developerIdRaw, 10) : developerIdRaw;
+  const basePort = Number(variables.port || 3000);
+  const hostPort = basePort + (Number.isFinite(developerIdNum) ? developerIdNum : 0) * 100;
+  const fd = variables.frontDoorRouting;
+  if (fd && fd.enabled === true && fd.pattern) {
+    const mount = normalizeFrontDoorPatternForHealth(fd.pattern);
+    if (mount && mount !== '/') {
+      return joinUrlPath(`http://localhost:${hostPort}`, mount).replace(/\/+$/, '');
+    }
+  }
+  return `http://localhost:${hostPort}`;
+}
+
+/**
+ * Controller URL for CLI HTTP calls on a remote dev host (builder-server).
+ * Keeps the public Traefik URL when reachable; otherwise falls back to localhost.
+ *
+ * @async
+ * @returns {Promise<string>}
+ */
+async function resolveCliPlatformControllerUrl() {
+  const publicUrl = await resolvePlatformControllerUrl();
+  const remoteServer = await config.getRemoteServer();
+  if (!remoteServer || !String(remoteServer).trim()) {
+    return publicUrl;
+  }
+  try {
+    const { checkHealthEndpoint } = require('./health-check-request');
+    const healthUrl = `${String(publicUrl).replace(/\/+$/, '')}/health`;
+    if (await checkHealthEndpoint(healthUrl)) {
+      return publicUrl;
+    }
+  } catch {
+    // fall through to localhost
+  }
+  return resolveLocalhostPlatformControllerUrl(MISO_CONTROLLER_APP);
+}
+
 module.exports = {
   MISO_CONTROLLER_APP,
   loadAppVariables,
   loadBundledApplicationVariables,
   computeAppBaseUrl,
-  resolvePlatformControllerUrl
+  resolvePlatformControllerUrl,
+  resolveLocalhostPlatformControllerUrl,
+  resolveCliPlatformControllerUrl
 };

package/lib/utils/url-declarative-public-base.js

@@ -10,26 +10,11 @@
 
 const { expandFrontDoorHostPlaceholders } = require('./compose-generator');
 const { publishedHostPort, localHostPort } = require('./declarative-url-ports');
-
-/**
- * Public URL authorities that must use `http://` (browsers hit loopback without TLS in practice).
- *
- * @param {string} hostname - Parsed URL hostname
- * @returns {boolean}
- */
-function isLocalhostPublicSchemeHostname(hostname) {
-  const h = String(hostname || '').trim().toLowerCase();
-  if (!h) {
-    return false;
-  }
-  if (h === 'localhost') {
-    return true;
-  }
-  if (h === '127.0.0.1') {
-    return true;
-  }
-  return h === '::1';
-}
+const {
+  normalizeSetupPlatformMode,
+  SETUP_PLATFORM_MODE
+} = require('../core/setup-platform-mode');
+const { isLocalhostPublicSchemeHostname } = require('./localhost-public-host');
 
 /**
  * Expand frontDoorRouting.host placeholders for url:// (same rules as Traefik labels in compose-generator).
@@ -156,6 +141,28 @@ function templateUsesRemoteHostPlaceholder(hostTemplate) {
   return /\$\{REMOTE_HOST\}/.test(String(hostTemplate || ''));
 }
 
+/**
+ * HTTPS for Traefik front-door public host when infra TLS is on, remote-server is https,
+ * or setup mode is single-traefik/full (builder-server nginx edge TLS).
+ *
+ * @param {Object} opts
+ * @param {boolean} [opts.infraTlsEnabled]
+ * @param {string|null|undefined} [opts.remoteServer]
+ * @param {string|null|undefined} [opts.setupPlatformMode]
+ * @returns {boolean}
+ */
+function traefikFrontDoorUsesHttps(opts = {}) {
+  if (opts.infraTlsEnabled) {
+    return true;
+  }
+  const remote = String(opts.remoteServer || '').trim();
+  if (remote && /^https:\/\//i.test(remote)) {
+    return true;
+  }
+  const mode = normalizeSetupPlatformMode(opts.setupPlatformMode);
+  return mode === SETUP_PLATFORM_MODE.SINGLE_TRAEFIK || mode === SETUP_PLATFORM_MODE.FULL;
+}
+
 /**
  * @param {Object} opts - same shape as computePublicUrlBaseString
  * @returns {string|null}
@@ -167,7 +174,6 @@ function buildTraefikPublicBaseIfApplicable(opts) {
     hostTemplate,
     developerIdRaw,
     remoteServer,
-    infraTlsEnabled,
     profile,
     developerIdNum
   } = opts;
@@ -189,8 +195,7 @@ function buildTraefikPublicBaseIfApplicable(opts) {
   if (!expanded) {
     return null;
   }
-  // Scheme follows global `tlsEnabled` (`up-infra --tls`) only — not `frontDoorRouting.tls` when infra TLS is off.
-  const useHttps = Boolean(infraTlsEnabled);
+  const useHttps = traefikFrontDoorUsesHttps(opts);
   let scheme = useHttps ? 'https' : 'http';
   if (isLocalhostPublicSchemeHostname(expanded)) {
     scheme = 'http';
@@ -210,7 +215,8 @@ function buildTraefikPublicBaseIfApplicable(opts) {
  * @param {'docker'|'local'} opts.profile
  * @param {number} opts.listenPort
  * @param {number} opts.developerIdNum
- * @param {boolean} [opts.infraTlsEnabled] - `tlsEnabled` from ~/.aifabrix/config.yaml (`up-infra --tls`); Traefik front-door public bases use **`https`** only when this is **true** (even if `frontDoorRouting.tls` is **false**). When **false**, front-door bases use **`http`** regardless of `frontDoorRouting.tls`. Loopback hostnames stay **http** always.
+ * @param {boolean} [opts.infraTlsEnabled] - `tlsEnabled` from ~/.aifabrix/config.yaml (`up-infra --tls`). Traefik front-door public bases also use **`https`** when `remote-server` is **`https://`** or `setupPlatformMode` is **`single-traefik`** / **`full`** (builder-server nginx edge TLS). Loopback hostnames stay **http** always.
+ * @param {string|null|undefined} [opts.setupPlatformMode] - From config; used with remote-server for edge TLS scheme
  * @param {boolean} [opts.pathActive] - traefik ∧ frontDoorRouting.enabled; required for Traefik host branch (plan 124)
  * @param {boolean|undefined} [opts.declarativePublicUrlsUseLocalhost] - **`true`**: force localhost authority (+ port rules below). **`false`**: allow `remote-server` as authority when Traefik is on, or when global `traefik` is not `false` and per-app `proxy` opts in without Traefik. **`undefined`**: default — omit `remote-server` when Traefik is off so published services use `http://localhost:<port>` (e.g. `af setup` / device login URLs). When user config has **`traefik: false`**, expansion forces localhost for public bases regardless of per-app `proxy`.
  * @returns {string}
@@ -270,5 +276,7 @@ function computePublicUrlBaseString(opts) {
 module.exports = {
   expandFrontDoorHostTemplateForUrls,
   computePublicUrlBaseString,
-  resolveHostPortForDeclarativePublic
+  resolveHostPortForDeclarativePublic,
+  isLocalhostPublicSchemeHostname,
+  traefikFrontDoorUsesHttps
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aifabrix/builder",
-  "version": "2.47.0",
+  "version": "2.47.1",
   "description": "AI Fabrix Local Fabric & Deployment SDK",
   "main": "lib/index.js",
   "bin": {