cloudcruise 1.0.0 → 1.1.0

package/dist/vault/types.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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;
+    proxy_setting?: 'random' | 'static' | 'country' | 'custom' | null;
+    proxy_value?: 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,34 @@
+/**
+ * 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), and
+ * proxy_value when proxy_setting is "custom" (the bring-your-own proxy URL).
+ * @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,122 @@
+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), and
+ * proxy_value when proxy_setting is "custom" (the bring-your-own proxy URL).
+ * @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);
+    }
+    // proxy_value is meaningless to the backend without proxy_setting, which is
+    // also the discriminator that tells us whether to encrypt. Fail closed: a
+    // custom proxy URL (often with embedded credentials) must never be sent in
+    // plaintext because the caller forgot the mode on a partial update.
+    if (entry.proxy_value !== undefined &&
+        entry.proxy_value !== null &&
+        (entry.proxy_setting === undefined || entry.proxy_setting === null)) {
+        throw new Error("proxy_value requires proxy_setting. Pass proxy_setting: 'custom' for a " +
+            "bring-your-own proxy URL (so it is encrypted before sending), or " +
+            "'static'/'country' for a managed proxy.");
+    }
+    if (entry.proxy_setting === 'custom' &&
+        entry.proxy_value !== undefined &&
+        entry.proxy_value !== null) {
+        encryptedEntry.proxy_value = await encryptData(entry.proxy_value, 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 { }
+    }
+    if (entry.proxy_setting === 'custom' && typeof entry.proxy_value === 'string') {
+        try {
+            decryptedEntry.proxy_value = await decryptData(entry.proxy_value, 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>;
+}

package/dist/workflows/WorkflowsClient.js

@@ -0,0 +1,97 @@
+import { InputValidationError } from './types.js';
+export class WorkflowsClient {
+    makeRequest;
+    constructor(makeRequest) {
+        this.makeRequest = makeRequest;
+    }
+    /**
+     * Retrieves all workflows of the workspace the API key is associated with
+     */
+    async getAllWorkflows() {
+        return await this.makeRequest('GET', '/workflows');
+    }
+    /**
+     * Retrieves the JSON schema of the input variables for a specific workflow
+     * @param workflowId - The ID of the workflow
+     */
+    async getWorkflowMetadata(workflowId) {
+        const path = `/workflows/${workflowId}/metadata`;
+        return await this.makeRequest('GET', path);
+    }
+    /**
+     * Validates a payload against a workflow's input schema.
+     * Throws InputValidationError if invalid; resolves if valid.
+     */
+    async validateWorkflowInput(workflowId, payload) {
+        const { input_schema } = await this.getWorkflowMetadata(workflowId);
+        const schema = input_schema ?? {};
+        const properties = schema.properties ?? {};
+        const required = schema.required ?? [];
+        const disallowExtras = schema.additionalProperties === false;
+        // Check only required keys for presence and type
+        const missingRequired = required.filter((key) => payload[key] === undefined);
+        const invalidTypes = [];
+        const detectType = (v) => {
+            if (v === null)
+                return 'null';
+            if (Array.isArray(v))
+                return 'array';
+            if (typeof v === 'number')
+                return Number.isInteger(v) ? 'integer' : 'number';
+            return typeof v;
+        };
+        const allowedTypes = new Set(['array', 'boolean', 'integer', 'number', 'object', 'string', 'null']);
+        const expectedTypesOf = (def) => {
+            if (!def)
+                return [];
+            // Normalize to array-of-strings from either string | string[] | { type: string | string[] }
+            const raw = (typeof def === 'object' && !Array.isArray(def)) ? def.type : def;
+            if (!raw)
+                return [];
+            const arr = Array.isArray(raw) ? raw : [raw];
+            return arr
+                .map((t) => String(t).toLowerCase())
+                .filter((t) => allowedTypes.has(t));
+        };
+        const matches = (expected, actual) => {
+            if (expected.length === 0)
+                return true; // unknown => don't enforce
+            if (expected.includes(actual))
+                return true;
+            if (actual === 'integer' && expected.includes('number'))
+                return true;
+            return false;
+        };
+        // Validate types for:
+        // - all required keys that are present
+        // - optional keys if they exist in the payload
+        for (const [key, schemaDef] of Object.entries(properties)) {
+            if (payload[key] === undefined)
+                continue; // optional and not provided
+            const expected = expectedTypesOf(schemaDef);
+            const actual = detectType(payload[key]);
+            if (!matches(expected, actual)) {
+                const exp = expected.length ? expected : ['any'];
+                invalidTypes.push({ field: key, expected_display: exp.join(' | '), actual });
+            }
+        }
+        // If additionalProperties is false, collect unknown keys present in payload
+        const unknownKeys = disallowExtras
+            ? Object.keys(payload).filter((k) => !(k in properties))
+            : [];
+        if (missingRequired.length || invalidTypes.length || unknownKeys.length) {
+            const parts = [];
+            if (missingRequired.length)
+                parts.push(`missing required: ${missingRequired.join(', ')}`);
+            if (invalidTypes.length) {
+                parts.push(invalidTypes
+                    .map((e) => `${e.field}: expected ${e.expected_display}, got ${e.actual}`)
+                    .join('; '));
+            }
+            if (unknownKeys.length)
+                parts.push(`unknown keys: ${unknownKeys.join(', ')}`);
+            const message = `Workflow input validation failed: ${parts.join(' | ')}`;
+            throw new InputValidationError(message, missingRequired, invalidTypes, unknownKeys);
+        }
+    }
+}

package/dist/workflows/types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * CloudCruise Workflows API Type Definitions
+ */
+export interface Workflow {
+    id: string;
+    name: string;
+    description?: string | null;
+    created_at: string;
+    updated_at: string;
+    workspace_id: string;
+    created_by: string;
+    enable_popup_handling: boolean;
+    enable_xpath_recovery: boolean;
+    enable_error_code_generation: boolean;
+    enable_service_unavailable_recovery: boolean;
+    enable_action_timing_recovery: boolean;
+}
+export type WorkflowPropertySchema = string | string[] | {
+    type?: string | string[];
+    [key: string]: unknown;
+};
+export interface WorkflowInputSchema {
+    type?: 'object';
+    properties?: Record<string, WorkflowPropertySchema>;
+    required?: string[];
+    additionalProperties?: boolean;
+}
+export interface WorkflowMetadata {
+    input_schema: WorkflowInputSchema;
+}
+export interface InvalidTypeDetail {
+    field: string;
+    expected_display: string;
+    actual: string;
+}
+export declare class InputValidationError extends Error {
+    readonly missingRequired: string[];
+    readonly invalidTypes: InvalidTypeDetail[];
+    readonly unknownKeys: string[];
+    constructor(message?: string, missingRequired?: string[], invalidTypes?: InvalidTypeDetail[], unknownKeys?: string[]);
+}

package/dist/workflows/types.js

@@ -0,0 +1,15 @@
+/**
+ * CloudCruise Workflows API Type Definitions
+ */
+export class InputValidationError extends Error {
+    missingRequired;
+    invalidTypes;
+    unknownKeys;
+    constructor(message = 'Input validation failed', missingRequired = [], invalidTypes = [], unknownKeys = []) {
+        super(message);
+        this.name = 'InputValidationError';
+        this.missingRequired = missingRequired;
+        this.invalidTypes = invalidTypes;
+        this.unknownKeys = unknownKeys;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloudcruise",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "The official CloudCruise JS/TS client.",
   "homepage": "https://github.com/CloudCruise/cloudcruise-js#readme",
   "bugs": {
@@ -21,6 +21,7 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
+    "prepublishOnly": "npm run build",
     "test": "pnpm build && node --test test/*.test.js"
   },
   "devDependencies": {