cloudcruise 1.0.0 → 1.0.1

package/dist/utils/sse.js

@@ -0,0 +1,122 @@
+/**
+ * Open an SSE connection using either native EventSource (browser, cookie auth)
+ * or fetch streaming (Node 18+ and modern browsers) when custom headers are needed.
+ */
+export function openSSE(url, handlers, opts) {
+    const { onOpen, onEvent, onError, onClose } = handlers;
+    const { headers, withCredentials, signal } = opts ?? {};
+    const shouldUseEventSource = () => typeof window !== 'undefined' &&
+        'EventSource' in window &&
+        withCredentials === true &&
+        (!headers || Object.keys(headers).length === 0);
+    const parseJSON = (text) => {
+        try {
+            return text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            return text || undefined;
+        }
+    };
+    const createEventSourceConnection = () => {
+        const ES = window.EventSource;
+        const es = new ES(url, { withCredentials: true });
+        const onOpenHandler = () => onOpen?.();
+        const onErrorHandler = (e) => onError?.(e instanceof Error ? e : new Error('EventSource error'));
+        const onRunEvent = (e) => {
+            const raw = String(e.data ?? '');
+            const parsed = parseJSON(raw);
+            onEvent?.({ event: 'run.event', data: parsed, id: e.lastEventId, raw });
+        };
+        const onPing = (e) => {
+            const raw = String(e.data ?? '');
+            const parsed = parseJSON(raw);
+            onEvent?.({ event: 'ping', data: parsed, id: e.lastEventId, raw });
+        };
+        es.addEventListener('open', onOpenHandler);
+        es.addEventListener('error', onErrorHandler);
+        es.addEventListener('run.event', onRunEvent);
+        es.addEventListener('ping', onPing);
+        if (signal) {
+            const onAbort = () => {
+                es.close();
+                onClose?.();
+            };
+            signal.addEventListener('abort', onAbort, { once: true });
+        }
+        return {
+            close() {
+                es.close();
+                onClose?.();
+            },
+        };
+    };
+    const createFetchConnection = () => {
+        const controller = new AbortController();
+        const abort = () => controller.abort();
+        if (signal)
+            signal.addEventListener('abort', abort, { once: true });
+        const parseFrame = (frame) => {
+            let event = 'message';
+            let data = '';
+            let id;
+            for (const line of frame.split(/\r?\n/)) {
+                if (!line || line.startsWith(':'))
+                    continue;
+                const idx = line.indexOf(':');
+                const field = idx === -1 ? line : line.slice(0, idx);
+                const value = idx === -1 ? '' : line.slice(idx + 1).trimStart();
+                if (field === 'event')
+                    event = value;
+                else if (field === 'data')
+                    data += (data ? '\n' : '') + value;
+                else if (field === 'id')
+                    id = value;
+            }
+            const parsed = parseJSON(data);
+            return { event, data: parsed, id, raw: frame };
+        };
+        (async () => {
+            try {
+                const res = await fetch(url, {
+                    method: 'GET',
+                    headers: {
+                        Accept: 'text/event-stream',
+                        'Cache-Control': 'no-cache',
+                        ...(headers ?? {}),
+                    },
+                    credentials: withCredentials ? 'include' : 'same-origin',
+                    signal: controller.signal,
+                });
+                if (!res.ok || !res.body)
+                    throw new Error(`SSE HTTP ${res.status}`);
+                onOpen?.();
+                const reader = res.body.getReader();
+                const decoder = new TextDecoder();
+                let buffer = '';
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    const chunk = decoder.decode(value, { stream: true });
+                    const parts = (buffer + chunk).split(/\r?\n\r?\n/);
+                    buffer = parts.pop() ?? '';
+                    for (const frame of parts) {
+                        const evt = parseFrame(frame);
+                        onEvent?.(evt);
+                    }
+                }
+                onClose?.();
+            }
+            catch (err) {
+                onError?.(err instanceof Error ? err : new Error(String(err)));
+            }
+        })();
+        return {
+            close() {
+                abort();
+                onClose?.();
+            },
+        };
+    };
+    return shouldUseEventSource() ? createEventSourceConnection() : createFetchConnection();
+}

package/dist/vault/VaultClient.d.ts

@@ -0,0 +1,55 @@
+import type { GetVaultEntriesFilters, VaultEntry, VaultTfaCode } from './types.js';
+export declare class VaultClient {
+    private readonly makeRequest;
+    private readonly encryptionKey;
+    constructor(makeRequest: <T = any>(method: 'GET' | 'POST' | 'PUT' | 'DELETE', path: string, body?: any) => Promise<T>, encryptionKey: string);
+    /**
+     * Creates a new vault entry
+     */
+    create(domain: string, permissioned_user_id: string, options?: Partial<Omit<VaultEntry, 'id' | 'created_at' | 'domain' | 'permissioned_user_id'>>): Promise<VaultEntry>;
+    /**
+     * Gets vault entries, optionally filtered
+     * @param filters - Optional filters for the request
+     * @param filters.permissioned_user_id - Filter by user ID
+     * @param filters.domain - Filter by domain
+     * @param filters.decryptCredentials - Whether to decrypt sensitive fields (default: true)
+     */
+    get(filters?: GetVaultEntriesFilters): Promise<VaultEntry[]>;
+    /**
+     * Gets the current 2FA code for a single vault entry.
+     *
+     * The code returned depends on the credential's 2FA method:
+     * - Authenticator (TOTP): a freshly generated code, with `expires_in_seconds`.
+     * - Email: the most recently received code (within the freshness window), with `received_at`.
+     *
+     * SMS and magic-link credentials are not supported (the endpoint returns 409).
+     *
+     * @param permissioned_user_id - User identifier for the vault entry
+     * @param domain - Target domain of the vault entry
+     */
+    getTfaCode(permissioned_user_id: string, domain: string): Promise<VaultTfaCode>;
+    /**
+     * Updates an existing vault entry
+     * @param updates - Vault entry updates including required fields
+     * @param updates.permissioned_user_id - Required: User identifier for the vault entry
+     * @param updates.user_name - Required: Username or email
+     * @param updates.password - Required: User password
+     * @param updates.domain - Required: Target domain for the credentials
+     */
+    update(updates: Partial<VaultEntry> & {
+        permissioned_user_id: string;
+        user_name: string;
+        password: string;
+        domain: string;
+    }): Promise<VaultEntry>;
+    /**
+     * Deletes a vault entry by domain and permissioned user ID
+     * @param params - Object containing domain and permissioned_user_id
+     * @param params.domain - The domain of the vault entry to delete
+     * @param params.permissioned_user_id - The permissioned user ID of the vault entry to delete
+     */
+    delete(params: {
+        domain: string;
+        permissioned_user_id: string;
+    }): Promise<void>;
+}

package/dist/vault/VaultClient.js

@@ -0,0 +1,115 @@
+import { encryptSensitiveFields, decryptSensitiveFields } from './utils.js';
+export class VaultClient {
+    makeRequest;
+    encryptionKey;
+    constructor(makeRequest, encryptionKey) {
+        this.makeRequest = makeRequest;
+        this.encryptionKey = encryptionKey;
+    }
+    /**
+     * Creates a new vault entry
+     */
+    async create(domain, permissioned_user_id, options) {
+        const entry = {
+            domain,
+            permissioned_user_id,
+            ...options
+        };
+        let processedEntry = { ...entry };
+        // Encrypt sensitive fields
+        processedEntry = await encryptSensitiveFields(processedEntry, this.encryptionKey);
+        const response = await this.makeRequest('POST', '/vault', processedEntry);
+        // Decrypt response using encryption key
+        return await decryptSensitiveFields(response, this.encryptionKey);
+    }
+    /**
+     * Gets vault entries, optionally filtered
+     * @param filters - Optional filters for the request
+     * @param filters.permissioned_user_id - Filter by user ID
+     * @param filters.domain - Filter by domain
+     * @param filters.decryptCredentials - Whether to decrypt sensitive fields (default: true)
+     */
+    async get(filters) {
+        let path = '/vault';
+        if (filters && (filters.permissioned_user_id || filters.domain)) {
+            const params = new URLSearchParams();
+            if (filters.permissioned_user_id) {
+                params.append('permissioned_user_id', filters.permissioned_user_id);
+            }
+            if (filters.domain) {
+                params.append('domain', filters.domain);
+            }
+            path += `?${params.toString()}`;
+        }
+        const response = await this.makeRequest('GET', path);
+        let entries = Array.isArray(response) ? response : [response];
+        // Conditionally decrypt sensitive fields based on decryptCredentials flag
+        const shouldDecrypt = filters?.decryptCredentials !== false;
+        if (shouldDecrypt) {
+            entries = await Promise.all(entries.map(entry => decryptSensitiveFields(entry, this.encryptionKey)));
+        }
+        return entries;
+    }
+    /**
+     * Gets the current 2FA code for a single vault entry.
+     *
+     * The code returned depends on the credential's 2FA method:
+     * - Authenticator (TOTP): a freshly generated code, with `expires_in_seconds`.
+     * - Email: the most recently received code (within the freshness window), with `received_at`.
+     *
+     * SMS and magic-link credentials are not supported (the endpoint returns 409).
+     *
+     * @param permissioned_user_id - User identifier for the vault entry
+     * @param domain - Target domain of the vault entry
+     */
+    async getTfaCode(permissioned_user_id, domain) {
+        if (!permissioned_user_id) {
+            throw new Error('permissioned_user_id is required to get a TFA code');
+        }
+        if (!domain) {
+            throw new Error('domain is required to get a TFA code');
+        }
+        const params = new URLSearchParams();
+        params.append('permissioned_user_id', permissioned_user_id);
+        params.append('domain', domain);
+        return await this.makeRequest('GET', `/vault/tfa-code?${params.toString()}`);
+    }
+    /**
+     * Updates an existing vault entry
+     * @param updates - Vault entry updates including required fields
+     * @param updates.permissioned_user_id - Required: User identifier for the vault entry
+     * @param updates.user_name - Required: Username or email
+     * @param updates.password - Required: User password
+     * @param updates.domain - Required: Target domain for the credentials
+     */
+    async update(updates) {
+        // Validate required fields
+        if (!updates.permissioned_user_id) {
+            throw new Error('permissioned_user_id is required for vault updates');
+        }
+        if (!updates.user_name) {
+            throw new Error('user_name is required for vault updates');
+        }
+        if (!updates.password) {
+            throw new Error('password is required for vault updates');
+        }
+        if (!updates.domain) {
+            throw new Error('domain is required for vault updates');
+        }
+        let processedEntry = { ...updates };
+        // Encrypt sensitive fields
+        processedEntry = await encryptSensitiveFields(processedEntry, this.encryptionKey);
+        const response = await this.makeRequest('PUT', '/vault', processedEntry);
+        // Decrypt response using encryption key
+        return await decryptSensitiveFields(response, this.encryptionKey);
+    }
+    /**
+     * Deletes a vault entry by domain and permissioned user ID
+     * @param params - Object containing domain and permissioned_user_id
+     * @param params.domain - The domain of the vault entry to delete
+     * @param params.permissioned_user_id - The permissioned user ID of the vault entry to delete
+     */
+    async delete(params) {
+        await this.makeRequest('DELETE', '/vault', params);
+    }
+}

package/dist/vault/types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * CloudCruise Vault API Type Definitions
+ */
+export interface VaultPostPutHeadersInBody {
+    name: string;
+    value: string;
+}
+export interface ProxyConfig {
+    enable: boolean;
+    target_ip?: string;
+}
+export interface VaultEntry {
+    id: string;
+    domain: string;
+    permissioned_user_id: string;
+    workspace_id?: string;
+    user_id?: string;
+    password?: string;
+    user_name?: string;
+    tfa_secret?: string;
+    user_agent?: string;
+    user_alias?: string;
+    location?: string;
+    ip_address?: string;
+    session_id?: string;
+    allow_multiple_sessions?: boolean;
+    prevent_concurrency_during_login?: boolean | null;
+    max_concurrency?: number | null;
+    expiry_time_from_last_use?: string | null;
+    expiry_time_from_session_data_set?: string | null;
+    tfa_method?: 'AUTHENTICATOR' | 'EMAIL' | 'SMS' | null;
+    cookies?: any;
+    local_storage?: any;
+    session_storage?: any;
+    persist_cookies?: boolean | null;
+    persist_local_storage?: boolean | null;
+    persist_session_storage?: boolean | null;
+    cookie_domain_to_store?: string | null;
+    proxy?: ProxyConfig;
+    proxy_string?: string | null;
+    headers?: VaultPostPutHeadersInBody[];
+    created_at?: string | null;
+    session_data_set_at?: string | null;
+    effective_expires_at?: string | null;
+}
+export interface GetVaultEntriesFilters {
+    permissioned_user_id?: string;
+    domain?: string;
+    decryptCredentials?: boolean;
+}
+/**
+ * The current 2FA code for a vault entry. `expires_in_seconds` is present for
+ * authenticator (TOTP) codes; `received_at` is present for email codes.
+ */
+export interface VaultTfaCode {
+    type: 'authenticator' | 'email';
+    code: string;
+    expires_in_seconds?: number;
+    received_at?: string;
+}

package/dist/vault/types.js

@@ -0,0 +1,4 @@
+/**
+ * CloudCruise Vault API Type Definitions
+ */
+export {};

package/dist/vault/utils.d.ts

@@ -0,0 +1,33 @@
+/**
+ * AES-256-GCM Encryption utilities for CloudCruise vault data
+ * Uses 12-byte IV and returns concatenated hex: iv(24 hex) + ciphertext + tag(32 hex)
+ */
+/**
+ * Encrypts sensitive data using AES-256-GCM
+ * @param data - Data to encrypt (will be JSON stringified)
+ * @param keyHex - Hex-encoded encryption key
+ * @returns Concatenated hex string: iv(24 hex) + ciphertext + tag(32 hex)
+ */
+export declare function encryptData(data: any, keyHex: string): Promise<string>;
+/**
+ * Decrypts data using AES-256-GCM
+ * @param encryptedHex - Concatenated hex: iv(24 hex) + ciphertext + tag(32 hex)
+ * @param keyHex - Hex-encoded encryption key
+ * @returns Decrypted and parsed data
+ */
+export declare function decryptData(encryptedHex: string, keyHex: string): Promise<any>;
+/**
+ * Encrypts sensitive fields in a vault entry
+ * Fields encrypted: user_name, password, tfa_secret (if present)
+ * @param entry - Vault entry with potentially sensitive data
+ * @param encryptionKey - Hex-encoded encryption key
+ * @returns Entry with encrypted sensitive fields
+ */
+export declare function encryptSensitiveFields(entry: any, encryptionKey: string): Promise<any>;
+/**
+ * Decrypts sensitive fields in a vault entry
+ * @param entry - Vault entry with encrypted sensitive fields
+ * @param encryptionKey - Hex-encoded encryption key
+ * @returns Entry with decrypted sensitive fields
+ */
+export declare function decryptSensitiveFields(entry: any, encryptionKey: string): Promise<any>;

package/dist/vault/utils.js

@@ -0,0 +1,99 @@
+import { createCipheriv, createDecipheriv, randomBytes } from 'crypto';
+/**
+ * AES-256-GCM Encryption utilities for CloudCruise vault data
+ * Uses 12-byte IV and returns concatenated hex: iv(24 hex) + ciphertext + tag(32 hex)
+ */
+/**
+ * Encrypts sensitive data using AES-256-GCM
+ * @param data - Data to encrypt (will be JSON stringified)
+ * @param keyHex - Hex-encoded encryption key
+ * @returns Concatenated hex string: iv(24 hex) + ciphertext + tag(32 hex)
+ */
+export async function encryptData(data, keyHex) {
+    try {
+        const key = Buffer.from(keyHex, 'hex');
+        const iv = randomBytes(12); // 12-byte IV for GCM
+        const jsonData = JSON.stringify(data);
+        const cipher = createCipheriv('aes-256-gcm', key, iv);
+        let encrypted = cipher.update(jsonData, 'utf8', 'hex');
+        encrypted += cipher.final('hex');
+        const tag = cipher.getAuthTag().toString('hex');
+        return iv.toString('hex') + encrypted + tag;
+    }
+    catch (error) {
+        throw new Error(`Encryption failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
+/**
+ * Decrypts data using AES-256-GCM
+ * @param encryptedHex - Concatenated hex: iv(24 hex) + ciphertext + tag(32 hex)
+ * @param keyHex - Hex-encoded encryption key
+ * @returns Decrypted and parsed data
+ */
+export async function decryptData(encryptedHex, keyHex) {
+    try {
+        if (typeof encryptedHex !== 'string' || encryptedHex.length < 56) {
+            throw new Error('Invalid encrypted payload');
+        }
+        const key = Buffer.from(keyHex, 'hex');
+        const iv = Buffer.from(encryptedHex.slice(0, 24), 'hex');
+        const tag = Buffer.from(encryptedHex.slice(-32), 'hex');
+        const encrypted = encryptedHex.slice(24, -32);
+        const decipher = createDecipheriv('aes-256-gcm', key, iv);
+        decipher.setAuthTag(tag);
+        let decrypted = decipher.update(encrypted, 'hex', 'utf8');
+        decrypted += decipher.final('utf8');
+        return JSON.parse(decrypted);
+    }
+    catch (error) {
+        throw new Error(`Decryption failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
+/**
+ * Encrypts sensitive fields in a vault entry
+ * Fields encrypted: user_name, password, tfa_secret (if present)
+ * @param entry - Vault entry with potentially sensitive data
+ * @param encryptionKey - Hex-encoded encryption key
+ * @returns Entry with encrypted sensitive fields
+ */
+export async function encryptSensitiveFields(entry, encryptionKey) {
+    const encryptedEntry = { ...entry };
+    if (entry.user_name !== undefined) {
+        encryptedEntry.user_name = await encryptData(entry.user_name, encryptionKey);
+    }
+    if (entry.password !== undefined) {
+        encryptedEntry.password = await encryptData(entry.password, encryptionKey);
+    }
+    if (entry.tfa_secret !== undefined) {
+        encryptedEntry.tfa_secret = await encryptData(entry.tfa_secret, encryptionKey);
+    }
+    return encryptedEntry;
+}
+/**
+ * Decrypts sensitive fields in a vault entry
+ * @param entry - Vault entry with encrypted sensitive fields
+ * @param encryptionKey - Hex-encoded encryption key
+ * @returns Entry with decrypted sensitive fields
+ */
+export async function decryptSensitiveFields(entry, encryptionKey) {
+    const decryptedEntry = { ...entry };
+    if (typeof entry.user_name === 'string') {
+        try {
+            decryptedEntry.user_name = await decryptData(entry.user_name, encryptionKey);
+        }
+        catch { }
+    }
+    if (typeof entry.password === 'string') {
+        try {
+            decryptedEntry.password = await decryptData(entry.password, encryptionKey);
+        }
+        catch { }
+    }
+    if (typeof entry.tfa_secret === 'string') {
+        try {
+            decryptedEntry.tfa_secret = await decryptData(entry.tfa_secret, encryptionKey);
+        }
+        catch { }
+    }
+    return decryptedEntry;
+}

package/dist/webhook/WebhookClient.d.ts

@@ -0,0 +1,15 @@
+import type { WebhookVerificationOptions } from './types.js';
+import type { EventType, WebhookMessage } from '../events/types.js';
+export declare class WebhookClient {
+    constructor();
+    /**
+     * Verifies the signature of an incoming webhook payload.
+     *
+     * @param receivedData - Raw request body supplied by the webhook sender.
+     * @param receivedSignature - Value from the `x-hmac-signature` request header. e.g req.headers["x-hmac-signature"]
+     * @param secretKey - Webhook secret configured in the CloudCruise portal.
+     * @param options - Optional overrides controlling signature verification behavior.
+     * @returns Verified webhook payload when the signature matches.
+     */
+    verifySignature<E extends EventType = EventType>(receivedData: any, receivedSignature: string, secretKey: string, options?: WebhookVerificationOptions): WebhookMessage<E>;
+}

package/dist/webhook/WebhookClient.js

@@ -0,0 +1,18 @@
+import { verifyMessage } from './utils.js';
+export class WebhookClient {
+    constructor() {
+        // No makeRequest needed for webhook verification
+    }
+    /**
+     * Verifies the signature of an incoming webhook payload.
+     *
+     * @param receivedData - Raw request body supplied by the webhook sender.
+     * @param receivedSignature - Value from the `x-hmac-signature` request header. e.g req.headers["x-hmac-signature"]
+     * @param secretKey - Webhook secret configured in the CloudCruise portal.
+     * @param options - Optional overrides controlling signature verification behavior.
+     * @returns Verified webhook payload when the signature matches.
+     */
+    verifySignature(receivedData, receivedSignature, secretKey, options) {
+        return verifyMessage(receivedData, receivedSignature, secretKey, options);
+    }
+}

package/dist/webhook/types.d.ts

@@ -0,0 +1,7 @@
+export declare class VerificationError extends Error {
+    readonly statusCode: number;
+    constructor(message?: string, statusCode?: number);
+}
+export interface WebhookVerificationOptions {
+    allowExpired?: boolean;
+}

package/dist/webhook/types.js

@@ -0,0 +1,8 @@
+export class VerificationError extends Error {
+    statusCode;
+    constructor(message = "Verification failed", statusCode = 400) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = "VerificationError";
+    }
+}

package/dist/webhook/utils.d.ts

@@ -0,0 +1,3 @@
+import type { EventType, WebhookMessage } from '../events/types.js';
+import { type WebhookVerificationOptions } from './types.js';
+export declare function verifyMessage<E extends EventType = EventType>(receivedData: any, receivedSignature: string, secretKey: string, options?: WebhookVerificationOptions): WebhookMessage<E>;

package/dist/webhook/utils.js

@@ -0,0 +1,49 @@
+import crypto from 'crypto';
+import { VerificationError } from './types.js';
+function verifyHmac(receivedData, receivedSignature, secretKey) {
+    const hmac = crypto.createHmac("sha256", secretKey);
+    hmac.update(receivedData);
+    const calculatedSignature = hmac.digest("hex");
+    const formattedReceivedSignature = receivedSignature.split("=")[1];
+    if (formattedReceivedSignature.length !== calculatedSignature.length) {
+        return false;
+    }
+    return crypto.timingSafeEqual(Buffer.from(calculatedSignature, "hex"), Buffer.from(formattedReceivedSignature, "hex"));
+}
+export function verifyMessage(receivedData, receivedSignature, secretKey, options) {
+    if (!receivedData) {
+        throw new VerificationError("Received request without body", 400);
+    }
+    if (!receivedSignature) {
+        throw new VerificationError("Missing HMAC signature", 400);
+    }
+    if (!secretKey) {
+        throw new VerificationError("Missing secret key", 400);
+    }
+    let dataJson;
+    let dataString;
+    if (typeof receivedData === 'string') {
+        dataString = receivedData;
+        try {
+            dataJson = JSON.parse(receivedData);
+        }
+        catch (error) {
+            throw new VerificationError(`Failed to decode JSON: ${error instanceof Error ? error.message : 'Unknown error'}`, 400);
+        }
+    }
+    else {
+        dataJson = receivedData;
+        dataString = JSON.stringify(receivedData);
+    }
+    const expiresAt = dataJson.expires_at;
+    if (!expiresAt) {
+        throw new VerificationError("No expiration date sent", 400);
+    }
+    if (!verifyHmac(dataString, receivedSignature, secretKey)) {
+        throw new VerificationError("Invalid HMAC signature", 401);
+    }
+    if (!options?.allowExpired && Date.now() / 1000 > expiresAt) {
+        throw new VerificationError("Webhook message expired", 400);
+    }
+    return dataJson;
+}

package/dist/workflows/WorkflowsClient.d.ts

@@ -0,0 +1,19 @@
+import type { Workflow, WorkflowMetadata } from './types.js';
+export declare class WorkflowsClient {
+    private readonly makeRequest;
+    constructor(makeRequest: <T = any>(method: 'GET' | 'POST' | 'PUT' | 'DELETE', path: string, body?: any) => Promise<T>);
+    /**
+     * Retrieves all workflows of the workspace the API key is associated with
+     */
+    getAllWorkflows(): Promise<Workflow[]>;
+    /**
+     * Retrieves the JSON schema of the input variables for a specific workflow
+     * @param workflowId - The ID of the workflow
+     */
+    getWorkflowMetadata(workflowId: string): Promise<WorkflowMetadata>;
+    /**
+     * Validates a payload against a workflow's input schema.
+     * Throws InputValidationError if invalid; resolves if valid.
+     */
+    validateWorkflowInput(workflowId: string, payload: Record<string, any>): Promise<void>;
+}