cloudcruise 0.0.1 → 0.0.2-alpha.1

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,5 @@
+import type { WebhookPayload, WebhookVerificationOptions } from './types.js';
+export declare class WebhookClient {
+    constructor();
+    verifySignature(receivedData: any, receivedSignature: string, secretKey: string, options?: WebhookVerificationOptions): WebhookPayload;
+}

package/dist/webhook/WebhookClient.js

@@ -0,0 +1,14 @@
+import { verifyMessage } from './utils.js';
+export class WebhookClient {
+    constructor() {
+        // No makeRequest needed for webhook verification
+    }
+    /*
+    1. receivedSignature will be in the request header: "x-hmac-signature"
+    2. receivedData will be the request body.
+    3. secretKey is the key you set when creating this webhook in the CloudCruise portal.
+    */
+    verifySignature(receivedData, receivedSignature, secretKey, options) {
+        return verifyMessage(receivedData, receivedSignature, secretKey, options);
+    }
+}

package/dist/webhook/types.d.ts

@@ -0,0 +1,13 @@
+import { EventType } from "../runs/types";
+export declare class VerificationError extends Error {
+    readonly statusCode: number;
+    constructor(message?: string, statusCode?: number);
+}
+export interface WebhookPayload {
+    event: EventType;
+    expires_at: number;
+    [key: string]: any;
+}
+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,2 @@
+import { type WebhookPayload, type WebhookVerificationOptions } from './types.js';
+export declare function verifyMessage(receivedData: any, receivedSignature: string, secretKey: string, options?: WebhookVerificationOptions): WebhookPayload;

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": "0.0.1",
+  "version": "0.0.2-alpha.1",
   "description": "The official CloudCruise JS/TS client.",
   "homepage": "https://github.com/CloudCruise/cloudcruise-js#readme",
   "bugs": {
@@ -13,8 +13,21 @@
   "license": "MIT",
   "author": "CloudCruise",
   "type": "module",
-  "main": "index.js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
   "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
     "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
   }
 }