@vizamodo/modo-dispatcher 1.1.77

package/dist/core/errors.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Error taxonomy for cli-dispatcher
+ *
+ * Goals:
+ * - Deterministic exit codes for viza-cli
+ * - Fail-fast, no side effects
+ * - Machine-readable + human-readable
+ */
+export declare enum DispatcherExitCode {
+    OK = 0,
+    INVALID_INPUT = 2,
+    GITHUB_NOT_LOGGED_IN = 10,
+    GITHUB_FORBIDDEN = 11,
+    DISPATCH_REJECTED = 20,
+    SESSION_TIMEOUT = 21,
+    GATEWAY_ERROR = 22,
+    ARTIFACT_NOT_FOUND = 30,
+    ARTIFACT_TOO_LARGE = 31,
+    ARTIFACT_INVALID_TYPE = 32,
+    INTERNAL_ERROR = 90
+}
+export interface DispatcherErrorOptions {
+    cause?: unknown;
+    details?: Record<string, any>;
+}
+/**
+ * Base dispatcher error
+ */
+export declare class DispatcherError extends Error {
+    readonly exitCode: DispatcherExitCode;
+    readonly details?: Record<string, any>;
+    readonly cause?: unknown;
+    constructor(message: string, exitCode: DispatcherExitCode, options?: DispatcherErrorOptions);
+}
+export declare class InvalidInputError extends DispatcherError {
+    constructor(message: string, options?: DispatcherErrorOptions);
+}
+export declare class GitHubNotLoggedInError extends DispatcherError {
+    constructor(message?: string, options?: DispatcherErrorOptions);
+}
+export declare class GitHubForbiddenError extends DispatcherError {
+    constructor(message?: string, options?: DispatcherErrorOptions);
+}
+export declare class DispatchRejectedError extends DispatcherError {
+    constructor(message?: string, options?: DispatcherErrorOptions);
+}
+export declare class SessionTimeoutError extends DispatcherError {
+    constructor(message?: string, options?: DispatcherErrorOptions);
+}
+export declare class GatewayError extends DispatcherError {
+    constructor(message?: string, options?: DispatcherErrorOptions);
+}
+export declare class ArtifactNotFoundError extends DispatcherError {
+    constructor(message?: string, options?: DispatcherErrorOptions);
+}
+export declare class ArtifactTooLargeError extends DispatcherError {
+    constructor(message?: string, options?: DispatcherErrorOptions);
+}
+export declare class ArtifactInvalidTypeError extends DispatcherError {
+    constructor(message?: string, options?: DispatcherErrorOptions);
+}
+export declare class InternalDispatcherError extends DispatcherError {
+    constructor(message?: string, options?: DispatcherErrorOptions);
+}
+/**
+ * Normalize unknown errors into DispatcherError
+ * Used by viza-cli boundary
+ */
+export declare function normalizeDispatcherError(err: unknown): DispatcherError;

package/dist/core/errors.js

@@ -0,0 +1,121 @@
+/**
+ * Error taxonomy for cli-dispatcher
+ *
+ * Goals:
+ * - Deterministic exit codes for viza-cli
+ * - Fail-fast, no side effects
+ * - Machine-readable + human-readable
+ */
+export var DispatcherExitCode;
+(function (DispatcherExitCode) {
+    DispatcherExitCode[DispatcherExitCode["OK"] = 0] = "OK";
+    // Input / usage
+    DispatcherExitCode[DispatcherExitCode["INVALID_INPUT"] = 2] = "INVALID_INPUT";
+    // Auth / permission
+    DispatcherExitCode[DispatcherExitCode["GITHUB_NOT_LOGGED_IN"] = 10] = "GITHUB_NOT_LOGGED_IN";
+    DispatcherExitCode[DispatcherExitCode["GITHUB_FORBIDDEN"] = 11] = "GITHUB_FORBIDDEN";
+    // Network / gateway
+    DispatcherExitCode[DispatcherExitCode["DISPATCH_REJECTED"] = 20] = "DISPATCH_REJECTED";
+    DispatcherExitCode[DispatcherExitCode["SESSION_TIMEOUT"] = 21] = "SESSION_TIMEOUT";
+    DispatcherExitCode[DispatcherExitCode["GATEWAY_ERROR"] = 22] = "GATEWAY_ERROR";
+    // Artifacts / logs
+    DispatcherExitCode[DispatcherExitCode["ARTIFACT_NOT_FOUND"] = 30] = "ARTIFACT_NOT_FOUND";
+    DispatcherExitCode[DispatcherExitCode["ARTIFACT_TOO_LARGE"] = 31] = "ARTIFACT_TOO_LARGE";
+    DispatcherExitCode[DispatcherExitCode["ARTIFACT_INVALID_TYPE"] = 32] = "ARTIFACT_INVALID_TYPE";
+    // Internal / unexpected
+    DispatcherExitCode[DispatcherExitCode["INTERNAL_ERROR"] = 90] = "INTERNAL_ERROR";
+})(DispatcherExitCode || (DispatcherExitCode = {}));
+/**
+ * Base dispatcher error
+ */
+export class DispatcherError extends Error {
+    exitCode;
+    details;
+    cause;
+    constructor(message, exitCode, options) {
+        super(message);
+        this.name = this.constructor.name;
+        this.exitCode = exitCode;
+        if (options?.details !== undefined) {
+            this.details = options.details;
+        }
+        this.cause = options?.cause;
+    }
+}
+/* -----------------------------
+ * Input / validation
+ * ----------------------------- */
+export class InvalidInputError extends DispatcherError {
+    constructor(message, options) {
+        super(message, DispatcherExitCode.INVALID_INPUT, options);
+    }
+}
+/* -----------------------------
+ * GitHub auth
+ * ----------------------------- */
+export class GitHubNotLoggedInError extends DispatcherError {
+    constructor(message = "Not logged in to GitHub", options) {
+        super(message, DispatcherExitCode.GITHUB_NOT_LOGGED_IN, options);
+    }
+}
+export class GitHubForbiddenError extends DispatcherError {
+    constructor(message = "GitHub permission denied", options) {
+        super(message, DispatcherExitCode.GITHUB_FORBIDDEN, options);
+    }
+}
+/* -----------------------------
+ * Gateway / dispatch
+ * ----------------------------- */
+export class DispatchRejectedError extends DispatcherError {
+    constructor(message = "Dispatch request rejected", options) {
+        super(message, DispatcherExitCode.DISPATCH_REJECTED, options);
+    }
+}
+export class SessionTimeoutError extends DispatcherError {
+    constructor(message = "Dispatch session timed out", options) {
+        super(message, DispatcherExitCode.SESSION_TIMEOUT, options);
+    }
+}
+export class GatewayError extends DispatcherError {
+    constructor(message = "Gateway error", options) {
+        super(message, DispatcherExitCode.GATEWAY_ERROR, options);
+    }
+}
+/* -----------------------------
+ * Artifacts
+ * ----------------------------- */
+export class ArtifactNotFoundError extends DispatcherError {
+    constructor(message = "Artifact not found. Possible cause: gateway R2 credentials rotated. Please redeploy the dispatch gateway and retry.", options) {
+        super(message, DispatcherExitCode.ARTIFACT_NOT_FOUND, options);
+    }
+}
+export class ArtifactTooLargeError extends DispatcherError {
+    constructor(message = "Artifact exceeds size limit", options) {
+        super(message, DispatcherExitCode.ARTIFACT_TOO_LARGE, options);
+    }
+}
+export class ArtifactInvalidTypeError extends DispatcherError {
+    constructor(message = "Invalid artifact content type", options) {
+        super(message, DispatcherExitCode.ARTIFACT_INVALID_TYPE, options);
+    }
+}
+/* -----------------------------
+ * Internal
+ * ----------------------------- */
+export class InternalDispatcherError extends DispatcherError {
+    constructor(message = "Internal dispatcher error", options) {
+        super(message, DispatcherExitCode.INTERNAL_ERROR, options);
+    }
+}
+/**
+ * Normalize unknown errors into DispatcherError
+ * Used by viza-cli boundary
+ */
+export function normalizeDispatcherError(err) {
+    if (err instanceof DispatcherError)
+        return err;
+    if (err instanceof Error) {
+        return new InternalDispatcherError(err.message, { cause: err });
+    }
+    return new InternalDispatcherError("Unknown error", { cause: err });
+}

package/dist/core/runtime-orchestrator.d.ts

@@ -0,0 +1,17 @@
+import { DispatchInput, DispatchMode, DispatchOptions, DispatchResult } from "../types/dispatcher.js";
+import { RuntimeContext } from "../runtime/runtime-context.js";
+export interface DispatchLifecycleResult {
+    runtimeContext: RuntimeContext;
+    result: DispatchResult;
+    sessionId: string;
+}
+/**
+ * Full dispatch lifecycle orchestration.
+ *
+ * Pipeline:
+ *   1. Auth & Bootstrap
+ *   2. Render banner
+ *   3. Dispatch to gateway (with bootstrap retry)
+ *   4. Wait for session result
+ */
+export declare function executeDispatchLifecycle(input: DispatchInput, options: DispatchOptions, mode: DispatchMode): Promise<DispatchLifecycleResult>;

package/dist/core/runtime-orchestrator.js

@@ -0,0 +1,47 @@
+import { ensureAuthAndBootstrap } from "./auth-bootstrap.js";
+import { dispatchWithBootstrapRetry } from "../gateway/dispatch-with-bootstrap-retry.js";
+import chalk from "chalk";
+import { extractSessionId } from "../utils/type-guards.js";
+import { renderDispatchBanner } from "../ui/banner.js";
+import { waitResultFromAccepted } from "../gateway/session-waiter.js";
+/**
+ * Full dispatch lifecycle orchestration.
+ *
+ * Pipeline:
+ *   1. Auth & Bootstrap
+ *   2. Render banner
+ *   3. Dispatch to gateway (with bootstrap retry)
+ *   4. Wait for session result
+ */
+export async function executeDispatchLifecycle(input, options, mode) {
+    // 1. Auth & Bootstrap
+    const { runtimeContext, bootstrapCfg } = await ensureAuthAndBootstrap(options);
+    // 2. Render banner
+    if (options.banner !== false) {
+        renderDispatchBanner(runtimeContext.claims.login ?? "unknown", runtimeContext.teams, input.allowedTeams, mode === "status");
+    }
+    // 3. Dispatch to gateway
+    const dispatched = await dispatchWithBootstrapRetry({
+        input,
+        mode,
+        teams: runtimeContext.teams,
+        bootstrap: bootstrapCfg,
+        targetEnv: options.auth.targetEnv,
+    });
+    const acceptedSessionId = extractSessionId(dispatched.accepted.artifacts) ?? "runtime";
+    if (dispatched.accepted.action === "dispatch" ||
+        dispatched.accepted.action === "reuse") {
+        const actionLabel = dispatched.accepted.action === "reuse"
+            ? chalk.yellow("REUSE")
+            : chalk.green("NEW");
+        console.log(chalk.gray("\n✓ Dispatch session established"));
+        console.log(`${chalk.gray("Session:")} ${acceptedSessionId}`);
+        console.log(`${chalk.gray("Mode   :")} ${actionLabel}`);
+    }
+    // 4. Wait for session result
+    return {
+        runtimeContext,
+        result: await waitResultFromAccepted(dispatched.accepted, input),
+        sessionId: acceptedSessionId,
+    };
+}

package/dist/core/runtime.d.ts

@@ -0,0 +1,16 @@
+import { AccessTokenService } from "../auth/session/access-token.js";
+import { TokenStateMachine } from "../auth/session/token-state.js";
+import { RefreshTokenService } from "../auth/session/refresh-token.js";
+export interface AuthRuntimeConfig {
+    refreshEndpoint: string;
+}
+export interface AuthRuntime {
+    accessTokenService: AccessTokenService;
+    refreshTokenService: RefreshTokenService;
+    tokenState: TokenStateMachine;
+    getBootstrapEndpoint(): string;
+}
+export declare function initAuthRuntime(config: AuthRuntimeConfig): AuthRuntime;
+export declare function getAuthRuntime(): AuthRuntime;
+export declare function tryGetAuthRuntime(): AuthRuntime | undefined;
+export declare function getAuthRuntimeRefreshEndpoint(): string | undefined;

package/dist/core/runtime.js

@@ -0,0 +1,52 @@
+import { AccessTokenService } from "../auth/session/access-token.js";
+import { TokenStateMachine } from "../auth/session/token-state.js";
+import { RefreshTokenService } from "../auth/session/refresh-token.js";
+import { KeychainStore } from "../auth/storage/keychain.js";
+import { MemoryTokenStore } from "../auth/storage/memory.js";
+let currentRuntime;
+let currentRefreshEndpoint;
+function deriveBootstrapEndpoint(refreshEndpoint) {
+    const url = new URL(refreshEndpoint);
+    const parts = url.pathname.split("/").filter(Boolean);
+    // Replace the last segment (usually "refresh") with "bootstrap"
+    parts.pop();
+    parts.push("bootstrap");
+    url.pathname = "/" + parts.join("/");
+    return url.toString();
+}
+export function initAuthRuntime(config) {
+    if (currentRuntime) {
+        if (currentRefreshEndpoint && currentRefreshEndpoint !== config.refreshEndpoint) {
+            throw new Error("Auth runtime already initialized with a different refresh endpoint");
+        }
+        return currentRuntime;
+    }
+    const memoryStore = new MemoryTokenStore();
+    const secureStore = new KeychainStore();
+    const accessTokenService = new AccessTokenService(memoryStore, secureStore);
+    const refreshTokenService = new RefreshTokenService(secureStore);
+    const tokenState = new TokenStateMachine(accessTokenService, refreshTokenService, {
+        refreshEndpoint: config.refreshEndpoint,
+    });
+    const bootstrapEndpoint = deriveBootstrapEndpoint(config.refreshEndpoint);
+    currentRuntime = {
+        accessTokenService,
+        refreshTokenService,
+        tokenState,
+        getBootstrapEndpoint: () => bootstrapEndpoint,
+    };
+    currentRefreshEndpoint = config.refreshEndpoint;
+    return currentRuntime;
+}
+export function getAuthRuntime() {
+    if (!currentRuntime) {
+        throw new Error("Auth runtime is not initialized");
+    }
+    return currentRuntime;
+}
+export function tryGetAuthRuntime() {
+    return currentRuntime;
+}
+export function getAuthRuntimeRefreshEndpoint() {
+    return currentRefreshEndpoint;
+}

package/dist/core/validation.d.ts

@@ -0,0 +1,2 @@
+import { DispatchInput } from "../types/dispatcher.js";
+export declare function assertDispatchInputStrict(input: DispatchInput): void;

package/dist/core/validation.js

@@ -0,0 +1,21 @@
+import { InvalidInputError } from "./errors.js";
+export function assertDispatchInputStrict(input) {
+    if (!input || typeof input !== "object") {
+        throw new InvalidInputError("Dispatch input must be an object");
+    }
+    if (!input.intent || typeof input.intent !== "string") {
+        throw new InvalidInputError("Missing dispatch intent");
+    }
+    if (!input.infraKey || typeof input.infraKey !== "string") {
+        throw new InvalidInputError("Missing infraKey");
+    }
+    if (!input.commandType || typeof input.commandType !== "string") {
+        throw new InvalidInputError("Missing commandType");
+    }
+    if (input.runType !== "infra" && input.runType !== "runtime") {
+        throw new InvalidInputError("runType must be 'infra' or 'runtime'");
+    }
+    if (!input.resourceId || typeof input.resourceId !== "string") {
+        throw new InvalidInputError("Missing resourceId");
+    }
+}

package/dist/crypto/encrypt.d.ts

@@ -0,0 +1,12 @@
+import { EncryptedPayload } from "../gateway/types.js";
+import { EncryptOptions } from "../types/dispatcher.js";
+/**
+ * Encrypt payload using X25519 + HKDF + AES-256-GCM.
+ *
+ * Security properties:
+ *  - Ephemeral client key per invocation
+ *  - Forward secrecy
+ *  - AEAD (authenticated encryption)
+ *  - No plaintext on wire
+ */
+export declare function encryptPayload(payload: Record<string, any>, opts: EncryptOptions): EncryptedPayload | null;

package/dist/crypto/encrypt.js

@@ -0,0 +1,80 @@
+import crypto from "crypto";
+/**
+ * Encrypt payload using X25519 + HKDF + AES-256-GCM.
+ *
+ * Security properties:
+ *  - Ephemeral client key per invocation
+ *  - Forward secrecy
+ *  - AEAD (authenticated encryption)
+ *  - No plaintext on wire
+ */
+export function encryptPayload(payload, opts) {
+    if (!opts?.serverPublicKeyRawB64) {
+        // allow caller to retry bootstrap/dispatch instead of breaking flow
+        return null;
+    }
+    // Normalize payload into an object we can safely enrich
+    let normalized;
+    if (payload === null || payload === undefined) {
+        normalized = {};
+    }
+    else if (typeof payload === "object") {
+        normalized = payload;
+    }
+    else {
+        // Primitive payloads are wrapped
+        normalized = { value: payload };
+    }
+    const created = Date.now();
+    const jti = crypto.randomBytes(16).toString("base64url");
+    const payloadStr = JSON.stringify(normalized);
+    // Load server public key from RAW X25519 bytes (base64)
+    const serverRaw = Buffer.from(opts.serverPublicKeyRawB64, "base64");
+    if (serverRaw.length !== 32) {
+        // invalid key (likely stale bootstrap or encoding mismatch)
+        // return null so dispatcher can trigger retry / bootstrap refresh
+        return null;
+    }
+    // Build SPKI DER for X25519 public key and import as KeyObject
+    // DER prefix for X25519 SPKI (OID 1.3.101.110) + BIT STRING header
+    const x25519SpkiPrefix = Buffer.from("302a300506032b656e032100", "hex");
+    const serverSpkiDer = Buffer.concat([x25519SpkiPrefix, serverRaw]);
+    const serverPubKey = crypto.createPublicKey({
+        key: serverSpkiDer,
+        format: "der",
+        type: "spki",
+    });
+    // Generate ephemeral client key pair
+    const clientKeyPair = crypto.generateKeyPairSync("x25519");
+    const clientPriv = clientKeyPair.privateKey;
+    const clientPub = clientKeyPair.publicKey;
+    // Derive shared secret
+    const sharedSecret = crypto.diffieHellman({
+        privateKey: clientPriv,
+        publicKey: serverPubKey,
+    });
+    // Derive symmetric key via HKDF (dynamic salt per message)
+    const salt = Buffer.from(`${created}.${jti}`, "utf8");
+    const aesKey = Buffer.from(crypto.hkdfSync("sha256", sharedSecret, salt, "viza-ecdh-key", 32));
+    // Encrypt using AES-256-GCM
+    const iv = crypto.randomBytes(12);
+    const cipher = crypto.createCipheriv("aes-256-gcm", aesKey, iv);
+    cipher.setAAD(Buffer.from(`${created}.${jti}`));
+    const encrypted = Buffer.concat([
+        cipher.update(payloadStr, "utf8"),
+        cipher.final(),
+    ]);
+    const tag = cipher.getAuthTag();
+    const result = {
+        alg: "x25519-hkdf-aes256gcm",
+        clientPub: clientPub
+            .export({ type: "spki", format: "der" })
+            .toString("base64"),
+        iv: iv.toString("base64"),
+        tag: tag.toString("base64"),
+        data: encrypted.toString("base64"),
+        created,
+        jti,
+    };
+    return result;
+}

package/dist/flows/email-otp-flow.d.ts

@@ -0,0 +1,7 @@
+import type { DispatchResult, DispatchInput, DispatchOptions, DispatchHandle, DispatchMode } from "../types/dispatcher.js";
+type EmailOtpFlowHooks = {
+    onBeforePrompt?: () => void;
+    onAfterPrompt?: () => void;
+};
+export declare function runEmailOtpFlow(input: DispatchInput, options: DispatchOptions, hooks?: EmailOtpFlowHooks, dispatcherCall?: (flowInput: DispatchInput, flowOptions: DispatchOptions, mode?: DispatchMode) => Promise<DispatchHandle>): Promise<DispatchResult>;
+export {};