@vizamodo/modo-dispatcher 1.1.77

package/dist/config/defaults.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Centralized default configuration values for cli-dispatcher.
+ *
+ * All hardcoded values should be moved here for SSOT compliance.
+ * Environment variables can override these defaults.
+ *
+ * @module config/defaults
+ */
+/**
+ * Default configuration values used across the dispatcher.
+ * These can be overridden via environment variables.
+ */
+export declare const DEFAULTS: {
+    /**
+     * Base URL for authentication endpoints.
+     * @env VIZA_AUTH_BASE
+     */
+    readonly AUTH_BASE: "https://auth.viza.io.vn/auth";
+    /**
+     * Default OAuth callback server port.
+     * @env VIZA_OAUTH_PORT
+     */
+    readonly OAUTH_CALLBACK_PORT: 39123;
+    /**
+     * Default gateway request timeout in milliseconds.
+     * @env VIZA_GATEWAY_TIMEOUT_MS
+     */
+    readonly GATEWAY_TIMEOUT_MS: 15000;
+    /**
+     * Default session wait timeout in milliseconds (10 minutes).
+     * @env VIZA_SESSION_TIMEOUT_MS
+     */
+    readonly SESSION_TIMEOUT_MS: number;
+    /**
+     * Default OAuth flow timeout in milliseconds (5 minutes).
+     * @env VIZA_OAUTH_TIMEOUT_MS
+     */
+    readonly OAUTH_TIMEOUT_MS: number;
+    /**
+     * Default token refresh buffer in seconds.
+     * Access tokens are considered expired this many seconds before actual expiry.
+     */
+    readonly TOKEN_REFRESH_BUFFER_SECONDS: 60;
+    /**
+     * Default WebSocket wait timeout in milliseconds (10 minutes).
+     */
+    readonly WEBSOCKET_TIMEOUT_MS: number;
+};
+/**
+ * Environment variable names for configuration overrides.
+ */
+export declare const ENV_KEYS: {
+    readonly AUTH_BASE: "VIZA_AUTH_BASE";
+    readonly OAUTH_PORT: "VIZA_OAUTH_PORT";
+    readonly GATEWAY_TIMEOUT_MS: "VIZA_GATEWAY_TIMEOUT_MS";
+    readonly SESSION_TIMEOUT_MS: "VIZA_SESSION_TIMEOUT_MS";
+    readonly OAUTH_TIMEOUT_MS: "VIZA_OAUTH_TIMEOUT_MS";
+};
+/**
+ * Runtime configuration derived from defaults and environment variables.
+ */
+export interface DispatcherConfig {
+    /** Base URL for authentication endpoints */
+    authBase: string;
+    /** OAuth callback server port */
+    oauthPort: number;
+    /** Gateway request timeout in ms */
+    gatewayTimeoutMs: number;
+    /** Session wait timeout in ms */
+    sessionTimeoutMs: number;
+    /** OAuth flow timeout in ms */
+    oauthTimeoutMs: number;
+}
+/**
+ * Create configuration with environment variable overrides.
+ *
+ * @example
+ * ```typescript
+ * import { createConfig } from './config/defaults.js';
+ *
+ * const config = createConfig();
+ * console.log(config.authBase); // 'https://auth.viza.io.vn/auth' or env override
+ * ```
+ */
+export declare function createConfig(): DispatcherConfig;
+/**
+ * Get the global configuration instance.
+ * Creates and caches configuration on first call.
+ */
+export declare function getConfig(): DispatcherConfig;
+/**
+ * Reset configuration (useful for testing).
+ */
+export declare function resetConfig(): void;

package/dist/config/defaults.js

@@ -0,0 +1,116 @@
+/**
+ * Centralized default configuration values for cli-dispatcher.
+ *
+ * All hardcoded values should be moved here for SSOT compliance.
+ * Environment variables can override these defaults.
+ *
+ * @module config/defaults
+ */
+/**
+ * Default configuration values used across the dispatcher.
+ * These can be overridden via environment variables.
+ */
+export const DEFAULTS = {
+    /**
+     * Base URL for authentication endpoints.
+     * @env VIZA_AUTH_BASE
+     */
+    AUTH_BASE: 'https://auth.viza.io.vn/auth',
+    /**
+     * Default OAuth callback server port.
+     * @env VIZA_OAUTH_PORT
+     */
+    OAUTH_CALLBACK_PORT: 39123,
+    /**
+     * Default gateway request timeout in milliseconds.
+     * @env VIZA_GATEWAY_TIMEOUT_MS
+     */
+    GATEWAY_TIMEOUT_MS: 15_000,
+    /**
+     * Default session wait timeout in milliseconds (10 minutes).
+     * @env VIZA_SESSION_TIMEOUT_MS
+     */
+    SESSION_TIMEOUT_MS: 10 * 60 * 1000,
+    /**
+     * Default OAuth flow timeout in milliseconds (5 minutes).
+     * @env VIZA_OAUTH_TIMEOUT_MS
+     */
+    OAUTH_TIMEOUT_MS: 5 * 60 * 1000,
+    /**
+     * Default token refresh buffer in seconds.
+     * Access tokens are considered expired this many seconds before actual expiry.
+     */
+    TOKEN_REFRESH_BUFFER_SECONDS: 60,
+    /**
+     * Default WebSocket wait timeout in milliseconds (10 minutes).
+     */
+    WEBSOCKET_TIMEOUT_MS: 10 * 60 * 1000,
+};
+/**
+ * Environment variable names for configuration overrides.
+ */
+export const ENV_KEYS = {
+    AUTH_BASE: 'VIZA_AUTH_BASE',
+    OAUTH_PORT: 'VIZA_OAUTH_PORT',
+    GATEWAY_TIMEOUT_MS: 'VIZA_GATEWAY_TIMEOUT_MS',
+    SESSION_TIMEOUT_MS: 'VIZA_SESSION_TIMEOUT_MS',
+    OAUTH_TIMEOUT_MS: 'VIZA_OAUTH_TIMEOUT_MS',
+};
+/**
+ * Parse a positive integer from environment variable.
+ * Returns undefined if not set or invalid.
+ */
+function parseEnvInt(value) {
+    if (!value)
+        return undefined;
+    const parsed = parseInt(value, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+/**
+ * Parse a string from environment variable.
+ * Returns undefined if empty or not set.
+ */
+function parseEnvString(value) {
+    return value?.trim() || undefined;
+}
+/**
+ * Create configuration with environment variable overrides.
+ *
+ * @example
+ * ```typescript
+ * import { createConfig } from './config/defaults.js';
+ *
+ * const config = createConfig();
+ * console.log(config.authBase); // 'https://auth.viza.io.vn/auth' or env override
+ * ```
+ */
+export function createConfig() {
+    return {
+        authBase: parseEnvString(process.env[ENV_KEYS.AUTH_BASE]) ?? DEFAULTS.AUTH_BASE,
+        oauthPort: parseEnvInt(process.env[ENV_KEYS.OAUTH_PORT]) ?? DEFAULTS.OAUTH_CALLBACK_PORT,
+        gatewayTimeoutMs: parseEnvInt(process.env[ENV_KEYS.GATEWAY_TIMEOUT_MS]) ?? DEFAULTS.GATEWAY_TIMEOUT_MS,
+        sessionTimeoutMs: parseEnvInt(process.env[ENV_KEYS.SESSION_TIMEOUT_MS]) ?? DEFAULTS.SESSION_TIMEOUT_MS,
+        oauthTimeoutMs: parseEnvInt(process.env[ENV_KEYS.OAUTH_TIMEOUT_MS]) ?? DEFAULTS.OAUTH_TIMEOUT_MS,
+    };
+}
+/**
+ * Cached configuration instance.
+ * Lazily initialized on first access.
+ */
+let _config;
+/**
+ * Get the global configuration instance.
+ * Creates and caches configuration on first call.
+ */
+export function getConfig() {
+    if (!_config) {
+        _config = createConfig();
+    }
+    return _config;
+}
+/**
+ * Reset configuration (useful for testing).
+ */
+export function resetConfig() {
+    _config = undefined;
+}

package/dist/core/auth-bootstrap.d.ts

@@ -0,0 +1,15 @@
+import type { DispatchOptions } from "../types/dispatcher.js";
+import type { RuntimeContext } from "../runtime/runtime-context.js";
+import type { GatewayBootstrapConfig } from "./bootstrap.js";
+export interface AuthBootstrapResult {
+    runtimeContext: RuntimeContext;
+    bootstrapCfg: GatewayBootstrapConfig;
+}
+/**
+ * Ensure the dispatcher runtime is authenticated and bootstrapped
+ * for the given target environment.
+ *
+ * Returns both the runtime context (for identity/claims) and
+ * the bootstrap config (for gateway dispatch).
+ */
+export declare function ensureAuthAndBootstrap(options: DispatchOptions): Promise<AuthBootstrapResult>;

package/dist/core/auth-bootstrap.js

@@ -0,0 +1,33 @@
+import { InvalidInputError } from "./errors.js";
+import { getConfig } from "../config/defaults.js";
+import { getAuthRuntime, getAuthRuntimeRefreshEndpoint, initAuthRuntime } from "./runtime.js";
+import { ensureAuthenticated } from "../auth/session/session-manager.js";
+import { ensureBootstrapped } from "./ensure-bootstrap.js";
+/**
+ * Ensure the dispatcher runtime is authenticated and bootstrapped
+ * for the given target environment.
+ *
+ * Returns both the runtime context (for identity/claims) and
+ * the bootstrap config (for gateway dispatch).
+ */
+export async function ensureAuthAndBootstrap(options) {
+    if (!options.auth) {
+        throw new InvalidInputError("Missing authentication options. Anonymous dispatch is not allowed.");
+    }
+    const config = getConfig();
+    const refreshEndpoint = `${config.authBase}/refresh`;
+    if (getAuthRuntimeRefreshEndpoint() !== refreshEndpoint) {
+        initAuthRuntime({ refreshEndpoint });
+    }
+    const runtimeContext = await ensureAuthenticated(getAuthRuntime(), {
+        loginEndpoint: `${config.authBase}/login`,
+        exchangeEndpoint: `${config.authBase}/exchange`,
+        refreshEndpoint,
+        logoutEndpoint: `${config.authBase}/logout`,
+    });
+    const bootstrapCfg = await ensureBootstrapped(options.auth.targetEnv);
+    if (!bootstrapCfg) {
+        throw new InvalidInputError("Bootstrap config is required for dispatch operations.");
+    }
+    return { runtimeContext, bootstrapCfg };
+}

package/dist/core/bootstrap.d.ts

@@ -0,0 +1,73 @@
+import { RuntimeEnv } from "../types/runtime-env.js";
+export type GatewayBootstrapConfig = {
+    endpoint: string;
+    encrypt: {
+        alg: "X25519";
+        format: "raw";
+        encoding: "base64";
+        publicKey: string;
+    };
+    auth?: {
+        loginEndpoint?: string;
+        exchangeEndpoint?: string;
+        refreshEndpoint?: string;
+        logoutEndpoint?: string;
+    };
+};
+/**
+ * Bootstrap config map returned by the gateway exchange & bootstrap endpoints.
+ * Keys are environment names (e.g. "dev", "prod").
+ */
+export type GatewayBootstrapMap = Record<string, GatewayBootstrapConfig>;
+export declare function getLocalGatewayConfigPath(runtimeEnv: RuntimeEnv): string;
+export declare function readLocalGatewayConfig(runtimeEnv: RuntimeEnv): GatewayBootstrapConfig | null;
+export declare function writeLocalGatewayConfig(runtimeEnv: RuntimeEnv, cfg: GatewayBootstrapConfig): void;
+/**
+ * Persist all bootstrap configs from a gateway bootstrap map to local storage.
+ * Overwrites existing cached configs.
+ */
+export declare function persistBootstrapMap(bootstrapMap: GatewayBootstrapMap): void;
+/**
+ * Refresh bootstrap config(s) from the authenticated gateway.
+ *
+ * Calls GET /auth/bootstrap with the current access token,
+ * then persists received configs locally.
+ *
+ * The bootstrap endpoint is derived internally from the auth runtime
+ * (never accepted from untrusted client input).
+ *
+ * @param runtimeEnv - If provided, only this env's config is returned.
+ *                     If omitted, all configs are fetched and persisted.
+ */
+export declare function refreshBootstrapFromGateway(runtimeEnv?: RuntimeEnv): Promise<GatewayBootstrapConfig>;
+/**
+ * Load bootstrap config for the given runtime environment.
+ *
+ * Strategy:
+ *   1. Read from local cache. If valid, return immediately.
+ *   2. If forceRefresh=true, call gateway /auth/bootstrap.
+ *   3. If autoRefresh=true and no local cache, call gateway /auth/bootstrap.
+ *   4. Otherwise throw.
+ */
+export interface LoadGatewayBootstrapConfigOptions {
+    autoRefresh?: boolean;
+    forceRefresh?: boolean;
+    /**
+     * If true, return null instead of throwing when bootstrap isn't available
+     * and there's no authenticated session to refresh from.
+     * This is useful for auth flows (login/logout) that shouldn't be blocked
+     * by missing bootstrap config.
+     */
+    optionalIfNoAuth?: boolean;
+}
+export declare function loadGatewayBootstrapConfig(runtimeEnv: RuntimeEnv, options?: LoadGatewayBootstrapConfigOptions): Promise<GatewayBootstrapConfig | null>;
+/**
+ * Manually refresh gateway bootstrap config for a specific environment.
+ * This is the function exposed to the CLI `bootstrap` command.
+ *
+ * The bootstrap endpoint is derived internally from the auth runtime
+ * (never accepted from untrusted client input).
+ *
+ * @param runtimeEnv - Target environment (e.g. "dev", "prod")
+ */
+export declare function bootstrapGatewayConfig(runtimeEnv: RuntimeEnv): Promise<GatewayBootstrapConfig>;

package/dist/core/bootstrap.js

@@ -0,0 +1,248 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { assertRuntimeEnv } from "../types/runtime-env.js";
+import { buildAuthHeader } from "../gateway/auth-header.js";
+import { getAuthRuntime, initAuthRuntime, tryGetAuthRuntime } from "./runtime.js";
+export function getLocalGatewayConfigPath(runtimeEnv) {
+    if (process.platform === "win32") {
+        const appData = process.env["APPDATA"]?.trim() ||
+            (process.env["USERPROFILE"]?.trim()
+                ? path.join(process.env["USERPROFILE"], "AppData", "Roaming")
+                : undefined);
+        if (!appData) {
+            throw new Error("\nMissing APPDATA/USERPROFILE env on Windows");
+        }
+        return path.join(appData, "viza", `gateway-${runtimeEnv}.json`);
+    }
+    return path.join(os.homedir(), ".config", "viza", `gateway-${runtimeEnv}.json`);
+}
+export function readLocalGatewayConfig(runtimeEnv) {
+    const filePath = getLocalGatewayConfigPath(runtimeEnv);
+    if (!fs.existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const raw = fs.readFileSync(filePath, "utf8");
+        const data = JSON.parse(raw);
+        assertGatewayBootstrapConfig(data, runtimeEnv);
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+function assertGatewayBootstrapConfig(data, runtimeEnv) {
+    if (!data || typeof data !== "object") {
+        throw new Error(`\nInvalid gateway-${runtimeEnv}.json: expected an object`);
+    }
+    if (typeof data.endpoint !== "string" || !data.endpoint) {
+        throw new Error(`\nInvalid gateway-${runtimeEnv}.json: missing endpoint`);
+    }
+    assertHttpsUrl(data.endpoint, `gateway-${runtimeEnv}.endpoint`);
+    const encrypt = data.encrypt;
+    if (!encrypt || typeof encrypt !== "object") {
+        throw new Error(`\nInvalid gateway-${runtimeEnv}.json: missing encrypt`);
+    }
+    if (encrypt.alg !== "X25519") {
+        throw new Error(`\nInvalid gateway-${runtimeEnv}.json: encrypt.alg must be X25519`);
+    }
+    if (encrypt.format !== "raw") {
+        throw new Error(`\nInvalid gateway-${runtimeEnv}.json: encrypt.format must be raw`);
+    }
+    if (encrypt.encoding !== "base64") {
+        throw new Error(`\nInvalid gateway-${runtimeEnv}.json: encrypt.encoding must be base64`);
+    }
+    if (typeof encrypt.publicKey !== "string" || !encrypt.publicKey) {
+        throw new Error(`\nInvalid gateway-${runtimeEnv}.json: missing encrypt.publicKey`);
+    }
+    assertX25519RawPublicKeyBase64(encrypt.publicKey, `gateway-${runtimeEnv}.encrypt.publicKey`);
+    if (data.auth !== undefined) {
+        if (!data.auth || typeof data.auth !== "object") {
+            throw new Error(`\nInvalid gateway-${runtimeEnv}.json: auth must be an object`);
+        }
+        if (data.auth.loginEndpoint !== undefined) {
+            assertHttpsUrl(data.auth.loginEndpoint, `gateway-${runtimeEnv}.auth.loginEndpoint`);
+        }
+        if (data.auth.exchangeEndpoint !== undefined) {
+            assertHttpsUrl(data.auth.exchangeEndpoint, `gateway-${runtimeEnv}.auth.exchangeEndpoint`);
+        }
+        if (data.auth.refreshEndpoint !== undefined) {
+            assertHttpsUrl(data.auth.refreshEndpoint, `gateway-${runtimeEnv}.auth.refreshEndpoint`);
+        }
+        if (data.auth.logoutEndpoint !== undefined) {
+            assertHttpsUrl(data.auth.logoutEndpoint, `gateway-${runtimeEnv}.auth.logoutEndpoint`);
+        }
+    }
+}
+function assertHttpsUrl(value, label) {
+    let u;
+    try {
+        u = new URL(value);
+    }
+    catch {
+        throw new Error(`\nInvalid ${label}: must be a valid URL`);
+    }
+    if (u.protocol !== "https:") {
+        throw new Error(`\nInvalid ${label}: must use https`);
+    }
+}
+function assertX25519RawPublicKeyBase64(value, label) {
+    const raw = Buffer.from(value, "base64");
+    if (raw.length !== 32) {
+        throw new Error(`\nInvalid ${label}: expected 32-byte X25519 raw key`);
+    }
+}
+export function writeLocalGatewayConfig(runtimeEnv, cfg) {
+    const filePath = getLocalGatewayConfigPath(runtimeEnv);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(cfg, null, 2) + "\n", "utf8");
+}
+/**
+ * Persist all bootstrap configs from a gateway bootstrap map to local storage.
+ * Overwrites existing cached configs.
+ */
+export function persistBootstrapMap(bootstrapMap) {
+    for (const [env, cfg] of Object.entries(bootstrapMap)) {
+        const runtimeEnv = env;
+        assertRuntimeEnv(runtimeEnv);
+        assertGatewayBootstrapConfig(cfg, runtimeEnv);
+        writeLocalGatewayConfig(runtimeEnv, cfg);
+    }
+}
+function getBootstrapEndpoint() {
+    return getAuthRuntime().getBootstrapEndpoint();
+}
+/**
+ * Refresh bootstrap config(s) from the authenticated gateway.
+ *
+ * Calls GET /auth/bootstrap with the current access token,
+ * then persists received configs locally.
+ *
+ * The bootstrap endpoint is derived internally from the auth runtime
+ * (never accepted from untrusted client input).
+ *
+ * @param runtimeEnv - If provided, only this env's config is returned.
+ *                     If omitted, all configs are fetched and persisted.
+ */
+export async function refreshBootstrapFromGateway(runtimeEnv) {
+    console.log("[auth] refreshing gateway bootstrap config...");
+    const bootstrapEndpoint = getBootstrapEndpoint();
+    let res;
+    try {
+        const headers = await buildAuthHeader();
+        res = await fetch(bootstrapEndpoint, {
+            method: "GET",
+            headers,
+        });
+    }
+    catch (err) {
+        console.error(`[auth] failed to refresh gateway bootstrap config: ${err.message}`);
+        throw new Error(`\nFailed to reach gateway bootstrap endpoint.\n${err.message}`);
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        console.error(`[auth] failed to refresh gateway bootstrap config: HTTP ${res.status}`);
+        throw new Error(`\nGateway bootstrap refresh failed: HTTP ${res.status}${body ? `\n${body}` : ""}`);
+    }
+    let json;
+    try {
+        json = (await res.json());
+    }
+    catch {
+        console.error("\n[auth] failed to refresh gateway bootstrap config: invalid JSON response");
+        throw new Error("\nGateway bootstrap response is not valid JSON");
+    }
+    if (json.success !== true || !json.bootstrap) {
+        console.error("\n[auth] failed to refresh gateway bootstrap config: invalid response structure");
+        throw new Error("\nGateway bootstrap response missing success or bootstrap field");
+    }
+    // Persist all received configs locally
+    persistBootstrapMap(json.bootstrap);
+    console.log("\n[auth] gateway bootstrap config refreshed successfully");
+    // Return the requested env's config, or the only one available
+    if (runtimeEnv) {
+        const cfg = json.bootstrap[runtimeEnv];
+        if (!cfg) {
+            const available = Object.keys(json.bootstrap).join(", ");
+            throw new Error(`\nGateway bootstrap response does not contain config for "${runtimeEnv}". Available: [${available}]`);
+        }
+        return cfg;
+    }
+    // If no specific env requested and there's exactly one, return it
+    const keys = Object.keys(json.bootstrap);
+    if (keys.length === 1) {
+        return json.bootstrap[keys[0]];
+    }
+    throw new Error("\nMultiple bootstrap environments returned but no target specified. " +
+        `Available: [${keys.join(", ")}]`);
+}
+export async function loadGatewayBootstrapConfig(runtimeEnv, options) {
+    assertRuntimeEnv(runtimeEnv);
+    if (options?.forceRefresh) {
+        return await refreshBootstrapFromGateway(runtimeEnv);
+    }
+    const local = readLocalGatewayConfig(runtimeEnv);
+    if (local) {
+        return local;
+    }
+    if (options?.autoRefresh) {
+        // Only attempt auto-refresh when an auth runtime is available and
+        // there is a refresh token to use. Calling the gateway bootstrap
+        // endpoint without a refresh token leads to noisy failures when
+        // running auth login/logout (the CLI may check bootstrap before
+        // login). Avoid making the network call in that case and return null
+        // to indicate bootstrap is not available yet.
+        //
+        // IMPORTANT: This breaks the circular dependency:
+        //   - login no longer requires bootstrap to exist
+        //   - bootstrap refresh only happens AFTER authentication succeeds
+        const rt = tryGetAuthRuntime();
+        if (!rt) {
+            // No auth runtime - return null to indicate bootstrap not available.
+            // This allows auth flows (login/logout) to proceed without requiring
+            // bootstrap config. Bootstrap will be fetched after successful login.
+            return null;
+        }
+        // Check for presence of refresh token before attempting network refresh.
+        // If there's no refresh token, don't call the gateway (it would fail
+        // with a confusing "Missing refresh token" error). Return null instead.
+        const refreshToken = await rt.refreshTokenService.get();
+        if (!refreshToken) {
+            // No refresh token - return null to allow login flow to proceed.
+            return null;
+        }
+        return await refreshBootstrapFromGateway(runtimeEnv);
+    }
+    // No autoRefresh - if optionalIfNoAuth is true, return null instead of throwing
+    if (options?.optionalIfNoAuth) {
+        return null;
+    }
+    throw new Error(`\nLocal gateway-${runtimeEnv}.json missing or invalid. Please log in to refresh.`);
+}
+// ─── Client-facing bootstrap command ──────────────────────────────────────
+/**
+ * Manually refresh gateway bootstrap config for a specific environment.
+ * This is the function exposed to the CLI `bootstrap` command.
+ *
+ * The bootstrap endpoint is derived internally from the auth runtime
+ * (never accepted from untrusted client input).
+ *
+ * @param runtimeEnv - Target environment (e.g. "dev", "prod")
+ */
+export async function bootstrapGatewayConfig(runtimeEnv) {
+    console.log(`\n[auth] bootstrapping gateway config for ${runtimeEnv}...`);
+    // Ensure the auth runtime is initialized. The bootstrap flow needs the
+    // auth runtime to derive the bootstrap endpoint (it transforms the
+    // configured refresh endpoint into a bootstrap endpoint). When the CLI
+    // calls this function directly it may not have initialized the runtime
+    // yet, so initialize it with a sensible default (or override via
+    // VIZA_AUTH_REFRESH_ENDPOINT).
+    if (!tryGetAuthRuntime()) {
+        const defaultRefresh = process.env["VIZA_AUTH_REFRESH_ENDPOINT"] ?? "https://auth.viza.io.vn/auth/refresh";
+        initAuthRuntime({ refreshEndpoint: defaultRefresh });
+    }
+    const cfg = await refreshBootstrapFromGateway(runtimeEnv);
+    console.log(`\n[auth] gateway config for ${runtimeEnv} bootstrapped successfully`);
+    return cfg;
+}

package/dist/core/dispatcher.d.ts

@@ -0,0 +1,2 @@
+import { DispatchHandle, DispatchInput, DispatchMode, DispatchOptions } from "../types/dispatcher.js";
+export declare function dispatcherDispatch(input: DispatchInput, options: DispatchOptions, mode?: DispatchMode): Promise<DispatchHandle>;

package/dist/core/dispatcher.js

@@ -0,0 +1,28 @@
+import { runEmailOtpFlow } from "../flows/email-otp-flow.js";
+import { assertDispatchInputStrict } from "./validation.js";
+import { executeDispatchLifecycle } from "./runtime-orchestrator.js";
+export async function dispatcherDispatch(input, options, mode = "dispatch") {
+    assertDispatchInputStrict(input);
+    if (options.interactiveAuthFlow !== false && input.intent === "email.provision.otp") {
+        return {
+            sessionId: "interactive-email-otp",
+            wsUrl: "",
+            // Interactive flows may start before access token is available.
+            currentUser: "interactive",
+            async wait() {
+                // Forward CLI-provided prompt hooks so the runtime spinner /
+                // async log renderer can be suspended while readline owns stdout.
+                return runEmailOtpFlow(input, options, options.interactivePromptHooks, dispatcherDispatch);
+            },
+        };
+    }
+    const lifecycle = await executeDispatchLifecycle(input, options, mode);
+    return {
+        sessionId: lifecycle.sessionId,
+        wsUrl: "",
+        currentUser: lifecycle.runtimeContext.claims.login ?? "unknown",
+        async wait() {
+            return lifecycle.result;
+        },
+    };
+}

package/dist/core/ensure-bootstrap.d.ts

@@ -0,0 +1,3 @@
+import { GatewayBootstrapConfig } from "./bootstrap.js";
+import { RuntimeEnv } from "../types/runtime-env.js";
+export declare function ensureBootstrapped(runtimeEnv: RuntimeEnv): Promise<GatewayBootstrapConfig>;

package/dist/core/ensure-bootstrap.js

@@ -0,0 +1,25 @@
+import { loadGatewayBootstrapConfig, } from "./bootstrap.js";
+import { DispatchRejectedError } from "./errors.js";
+export async function ensureBootstrapped(runtimeEnv) {
+    // First try to load from local cache (non-auto refresh)
+    const local = await loadGatewayBootstrapConfig(runtimeEnv);
+    if (local) {
+        return local;
+    }
+    // Attempt auto-refresh using authenticated gateway (this may throw)
+    try {
+        const refreshed = await loadGatewayBootstrapConfig(runtimeEnv, {
+            autoRefresh: true,
+        });
+        if (refreshed) {
+            return refreshed;
+        }
+    }
+    catch (e) {
+        throw new DispatchRejectedError("Missing gateway bootstrap config and auto-bootstrap failed.\n" +
+            "Please log in to refresh your bootstrap config.", { cause: e });
+    }
+    // If we reached here, bootstrap was not available and auto-refresh did not produce one
+    throw new DispatchRejectedError("Missing gateway bootstrap config and auto-bootstrap failed.\n" +
+        "Please log in to refresh your bootstrap config.");
+}