mstro-app 0.1.47

package/dist/server/services/instances.js

@@ -0,0 +1,241 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+/**
+ * Instance Registry Service
+ *
+ * Manages multiple Mstro server instances
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+function clearStaleLock(lockPath) {
+    if (!existsSync(lockPath))
+        return;
+    try {
+        const lockTime = parseInt(readFileSync(lockPath, 'utf-8'), 10);
+        if (Date.now() - lockTime > 10000) {
+            try {
+                unlinkSync(lockPath);
+            }
+            catch { }
+        }
+    }
+    catch { }
+}
+function tryCreateLock(lockPath) {
+    try {
+        writeFileSync(lockPath, Date.now().toString(), { flag: 'wx' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function busyWait() {
+    const endTime = Date.now() + Math.random() * 50 + 10;
+    while (Date.now() < endTime) { /* busy wait */ }
+}
+function acquireLock(lockPath, timeout = 5000) {
+    const start = Date.now();
+    while (Date.now() - start < timeout) {
+        clearStaleLock(lockPath);
+        if (tryCreateLock(lockPath))
+            return true;
+        busyWait();
+    }
+    return false;
+}
+function releaseLock(lockPath) {
+    try {
+        unlinkSync(lockPath);
+    }
+    catch {
+        // Ignore errors when releasing lock
+    }
+}
+export class InstanceRegistry {
+    registryPath;
+    currentInstance = null;
+    heartbeatInterval = null;
+    constructor() {
+        const mstroDir = join(homedir(), '.mstro');
+        if (!existsSync(mstroDir)) {
+            mkdirSync(mstroDir, { recursive: true, mode: 0o700 });
+        }
+        this.registryPath = join(mstroDir, 'instances.json');
+    }
+    /**
+     * Register current instance
+     */
+    register(port, workingDirectory) {
+        const instance = {
+            id: `mstro-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+            port,
+            url: `http://localhost:${port}`,
+            workingDirectory,
+            startedAt: Date.now(),
+            lastHeartbeat: Date.now(),
+            pid: process.pid
+        };
+        this.currentInstance = instance;
+        this.saveInstance(instance);
+        this.startHeartbeat();
+        return instance;
+    }
+    /**
+     * Unregister current instance
+     */
+    unregister() {
+        if (this.currentInstance) {
+            this.removeInstance(this.currentInstance.id);
+            this.currentInstance = null;
+        }
+        this.stopHeartbeat();
+    }
+    /**
+     * Get current instance info
+     */
+    getCurrentInstance() {
+        return this.currentInstance;
+    }
+    /**
+     * Get all instances (with file locking to prevent race conditions)
+     */
+    static getAllInstances() {
+        const mstroDir = join(homedir(), '.mstro');
+        const registryPath = join(mstroDir, 'instances.json');
+        const lockPath = join(mstroDir, 'instances.lock');
+        if (!existsSync(registryPath)) {
+            return [];
+        }
+        const locked = acquireLock(lockPath, 3000);
+        try {
+            const data = readFileSync(registryPath, 'utf-8');
+            // Handle empty or whitespace-only content
+            if (!data || !data.trim()) {
+                return [];
+            }
+            const parsed = JSON.parse(data);
+            // Ensure we have an array
+            const instances = Array.isArray(parsed) ? parsed : [];
+            // Filter out stale instances (no heartbeat in last 2 minutes)
+            const now = Date.now();
+            const maxAge = 2 * 60 * 1000; // 2 minutes
+            return instances.filter(instance => now - instance.lastHeartbeat < maxAge);
+        }
+        catch (error) {
+            // If JSON is corrupted, log but don't spam - return empty and let next write fix it
+            if (error instanceof SyntaxError) {
+                console.warn('[InstanceRegistry] Registry file corrupted, will be recreated on next write');
+            }
+            else {
+                console.error('[InstanceRegistry] Failed to read instances registry:', error);
+            }
+            return [];
+        }
+        finally {
+            if (locked) {
+                releaseLock(lockPath);
+            }
+        }
+    }
+    /**
+     * Get instance by ID
+     */
+    static getInstance(id) {
+        const instances = InstanceRegistry.getAllInstances();
+        return instances.find(i => i.id === id) || null;
+    }
+    /**
+     * Save instance to registry (with file locking)
+     */
+    saveInstance(instance) {
+        const lockPath = join(homedir(), '.mstro', 'instances.lock');
+        const locked = acquireLock(lockPath, 5000);
+        try {
+            // Read current instances directly (without calling getAllInstances to avoid double-locking)
+            let instances = [];
+            if (existsSync(this.registryPath)) {
+                try {
+                    const data = readFileSync(this.registryPath, 'utf-8');
+                    if (data?.trim()) {
+                        const parsed = JSON.parse(data);
+                        instances = Array.isArray(parsed) ? parsed : [];
+                    }
+                }
+                catch {
+                    // If file is corrupted, start fresh
+                    instances = [];
+                }
+            }
+            // Filter out stale instances while we're at it
+            const now = Date.now();
+            const maxAge = 2 * 60 * 1000;
+            instances = instances.filter(i => i.id !== instance.id && now - i.lastHeartbeat < maxAge);
+            // Add new/updated instance
+            instances.push(instance);
+            // Write atomically by writing to temp file first then renaming
+            const tempPath = `${this.registryPath}.tmp`;
+            writeFileSync(tempPath, JSON.stringify(instances, null, 2), 'utf-8');
+            // Rename is atomic on most filesystems
+            renameSync(tempPath, this.registryPath);
+        }
+        finally {
+            if (locked) {
+                releaseLock(lockPath);
+            }
+        }
+    }
+    /**
+     * Remove instance from registry (with file locking)
+     */
+    removeInstance(id) {
+        const lockPath = join(homedir(), '.mstro', 'instances.lock');
+        const locked = acquireLock(lockPath, 5000);
+        try {
+            let instances = [];
+            if (existsSync(this.registryPath)) {
+                try {
+                    const data = readFileSync(this.registryPath, 'utf-8');
+                    if (data?.trim()) {
+                        const parsed = JSON.parse(data);
+                        instances = Array.isArray(parsed) ? parsed : [];
+                    }
+                }
+                catch {
+                    instances = [];
+                }
+            }
+            instances = instances.filter(i => i.id !== id);
+            const tempPath = `${this.registryPath}.tmp`;
+            writeFileSync(tempPath, JSON.stringify(instances, null, 2), 'utf-8');
+            renameSync(tempPath, this.registryPath);
+        }
+        finally {
+            if (locked) {
+                releaseLock(lockPath);
+            }
+        }
+    }
+    /**
+     * Start heartbeat to keep instance alive
+     */
+    startHeartbeat() {
+        this.heartbeatInterval = setInterval(() => {
+            if (this.currentInstance) {
+                this.currentInstance.lastHeartbeat = Date.now();
+                this.saveInstance(this.currentInstance);
+            }
+        }, 30000); // Every 30 seconds
+    }
+    /**
+     * Stop heartbeat
+     */
+    stopHeartbeat() {
+        if (this.heartbeatInterval) {
+            clearInterval(this.heartbeatInterval);
+            this.heartbeatInterval = null;
+        }
+    }
+}
+//# sourceMappingURL=instances.js.map

package/dist/server/services/instances.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instances.js","sourceRoot":"","sources":["../../../server/services/instances.ts"],"names":[],"mappings":"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"}

package/dist/server/services/pathUtils.d.ts

@@ -0,0 +1,47 @@
+export interface PathValidationResult {
+    valid: boolean;
+    resolvedPath: string;
+    error?: string;
+}
+/**
+ * Validate that a path is within the allowed working directory.
+ * Prevents path traversal attacks using .. or absolute paths.
+ *
+ * @param targetPath - The path to validate (relative or absolute)
+ * @param workingDir - The allowed working directory boundary
+ * @returns PathValidationResult with validation status and resolved path
+ */
+export declare function validatePathWithinWorkingDir(targetPath: string, workingDir: string): PathValidationResult;
+/**
+ * Validate both source and destination paths for rename/move operations.
+ * Both paths must be within the working directory.
+ *
+ * @param sourcePath - The source path
+ * @param destPath - The destination path
+ * @param workingDir - The allowed working directory boundary
+ * @returns Object with validation results for both paths
+ */
+export declare function validateBothPathsWithinWorkingDir(sourcePath: string, destPath: string, workingDir: string): {
+    valid: boolean;
+    resolvedSourcePath: string;
+    resolvedDestPath: string;
+    error?: string;
+};
+/**
+ * Get the relative path from working directory.
+ * Useful for returning user-friendly paths in responses.
+ *
+ * @param absolutePath - The absolute path
+ * @param workingDir - The working directory
+ * @returns Relative path from working directory
+ */
+export declare function getRelativePath(absolutePath: string, workingDir: string): string;
+/**
+ * Check if a path contains dangerous patterns that should be blocked.
+ * This is an additional layer of defense beyond path validation.
+ *
+ * @param path - The path to check
+ * @returns true if path contains dangerous patterns
+ */
+export declare function containsDangerousPatterns(path: string): boolean;
+//# sourceMappingURL=pathUtils.d.ts.map

package/dist/server/services/pathUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pathUtils.d.ts","sourceRoot":"","sources":["../../../server/services/pathUtils.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,OAAO,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,oBAAoB,CAoDtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iCAAiC,CAC/C,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB;IACD,KAAK,EAAE,OAAO,CAAC;IACf,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CA0BA;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAEhF;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAS/D"}

package/dist/server/services/pathUtils.js

@@ -0,0 +1,124 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+/**
+ * Path Utilities
+ *
+ * Secure path validation utilities to prevent path traversal attacks.
+ * All file explorer operations MUST validate paths through these functions.
+ */
+import { isAbsolute, normalize, relative, resolve } from 'node:path';
+/**
+ * Validate that a path is within the allowed working directory.
+ * Prevents path traversal attacks using .. or absolute paths.
+ *
+ * @param targetPath - The path to validate (relative or absolute)
+ * @param workingDir - The allowed working directory boundary
+ * @returns PathValidationResult with validation status and resolved path
+ */
+export function validatePathWithinWorkingDir(targetPath, workingDir) {
+    try {
+        // Normalize the working directory to get canonical path
+        const normalizedWorkingDir = resolve(workingDir);
+        // Resolve the target path relative to working directory
+        let resolvedPath;
+        if (isAbsolute(targetPath)) {
+            resolvedPath = resolve(targetPath);
+        }
+        else {
+            resolvedPath = resolve(normalizedWorkingDir, targetPath);
+        }
+        // Normalize to remove any .. or . segments
+        resolvedPath = normalize(resolvedPath);
+        // Check if the resolved path starts with the working directory
+        // Add trailing separator to prevent partial matches (e.g., /home/user vs /home/username)
+        const workingDirWithSep = normalizedWorkingDir.endsWith('/')
+            ? normalizedWorkingDir
+            : `${normalizedWorkingDir}/`;
+        const isWithinWorkingDir = resolvedPath === normalizedWorkingDir ||
+            resolvedPath.startsWith(workingDirWithSep);
+        if (!isWithinWorkingDir) {
+            // Log security violation for monitoring
+            console.error(`[PathUtils] SECURITY: Path traversal attempt blocked. ` +
+                `Target: "${targetPath}", Resolved: "${resolvedPath}", WorkingDir: "${normalizedWorkingDir}"`);
+            return {
+                valid: false,
+                resolvedPath: '',
+                error: 'Access denied: path is outside working directory'
+            };
+        }
+        return {
+            valid: true,
+            resolvedPath
+        };
+    }
+    catch (error) {
+        console.error('[PathUtils] Error validating path:', error);
+        return {
+            valid: false,
+            resolvedPath: '',
+            error: `Invalid path: ${error.message}`
+        };
+    }
+}
+/**
+ * Validate both source and destination paths for rename/move operations.
+ * Both paths must be within the working directory.
+ *
+ * @param sourcePath - The source path
+ * @param destPath - The destination path
+ * @param workingDir - The allowed working directory boundary
+ * @returns Object with validation results for both paths
+ */
+export function validateBothPathsWithinWorkingDir(sourcePath, destPath, workingDir) {
+    const sourceValidation = validatePathWithinWorkingDir(sourcePath, workingDir);
+    if (!sourceValidation.valid) {
+        return {
+            valid: false,
+            resolvedSourcePath: '',
+            resolvedDestPath: '',
+            error: `Source path error: ${sourceValidation.error}`
+        };
+    }
+    const destValidation = validatePathWithinWorkingDir(destPath, workingDir);
+    if (!destValidation.valid) {
+        return {
+            valid: false,
+            resolvedSourcePath: '',
+            resolvedDestPath: '',
+            error: `Destination path error: ${destValidation.error}`
+        };
+    }
+    return {
+        valid: true,
+        resolvedSourcePath: sourceValidation.resolvedPath,
+        resolvedDestPath: destValidation.resolvedPath
+    };
+}
+/**
+ * Get the relative path from working directory.
+ * Useful for returning user-friendly paths in responses.
+ *
+ * @param absolutePath - The absolute path
+ * @param workingDir - The working directory
+ * @returns Relative path from working directory
+ */
+export function getRelativePath(absolutePath, workingDir) {
+    return relative(resolve(workingDir), absolutePath);
+}
+/**
+ * Check if a path contains dangerous patterns that should be blocked.
+ * This is an additional layer of defense beyond path validation.
+ *
+ * @param path - The path to check
+ * @returns true if path contains dangerous patterns
+ */
+export function containsDangerousPatterns(path) {
+    const dangerousPatterns = [
+        /\0/, // Null bytes
+        /^~/, // Home directory expansion (should use absolute paths)
+        /\$\{/, // Variable expansion
+        /\$\(/, // Command substitution
+    ];
+    return dangerousPatterns.some(pattern => pattern.test(path));
+}
+//# sourceMappingURL=pathUtils.js.map

package/dist/server/services/pathUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pathUtils.js","sourceRoot":"","sources":["../../../server/services/pathUtils.ts"],"names":[],"mappings":"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"}

package/dist/server/services/platform.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Get machine identification string
+ * Format: "hostname @ node-vX.X.X platform (arch)"
+ * Example: "Jessica @ node-v22.21.1 linux (arm64)"
+ */
+export declare function getMachineIdentifier(): string;
+interface ConnectionCallbacks {
+    onConnected?: (connectionId: string) => void;
+    onDisconnected?: () => void;
+    onError?: (error: string) => void;
+    onWebConnected?: () => void;
+    onWebDisconnected?: () => void;
+    onRelayedMessage?: (message: any) => void;
+}
+/**
+ * Platform WebSocket connection with token-based authentication
+ */
+export declare class PlatformConnection {
+    private ws;
+    private reconnectTimeout;
+    private reconnectAttempts;
+    private maxReconnectAttempts;
+    private isIntentionallyClosed;
+    private workingDirectory;
+    private platformUrl;
+    private callbacks;
+    private connectionId;
+    private isConnected;
+    private tokenRefreshInterval;
+    private heartbeatInterval;
+    constructor(workingDirectory: string, callbacks?: ConnectionCallbacks, platformUrl?: string);
+    /**
+     * Refresh the device token if needed
+     */
+    private maybeRefreshToken;
+    /**
+     * Start periodic token refresh check
+     */
+    private startTokenRefreshCheck;
+    /**
+     * Start heartbeat to keep connection alive and refresh server-side TTL
+     */
+    private startHeartbeat;
+    /**
+     * Stop heartbeat
+     */
+    private stopHeartbeat;
+    /**
+     * Stop periodic token refresh check
+     */
+    private stopTokenRefreshCheck;
+    /**
+     * Connect to platform WebSocket
+     */
+    connect(): void;
+    private handleMessage;
+    private scheduleReconnect;
+    /**
+     * Send message to platform (will be relayed to web if connected)
+     */
+    send(message: any): void;
+    /**
+     * Check if connected to platform
+     */
+    isConnectedToPlatform(): boolean;
+    /**
+     * Disconnect from platform
+     */
+    disconnect(): void;
+}
+export {};
+//# sourceMappingURL=platform.d.ts.map

package/dist/server/services/platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../../../server/services/platform.ts"],"names":[],"mappings":"AAkFA;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAM7C;AAeD,UAAU,mBAAmB;IAC3B,WAAW,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,IAAI,CAAA;IAC5C,cAAc,CAAC,EAAE,MAAM,IAAI,CAAA;IAC3B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACjC,cAAc,CAAC,EAAE,MAAM,IAAI,CAAA;IAC3B,iBAAiB,CAAC,EAAE,MAAM,IAAI,CAAA;IAC9B,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,IAAI,CAAA;CAC1C;AAED;;GAEG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,gBAAgB,CAA6C;IACrE,OAAO,CAAC,iBAAiB,CAAI;IAC7B,OAAO,CAAC,oBAAoB,CAAK;IACjC,OAAO,CAAC,qBAAqB,CAAQ;IACrC,OAAO,CAAC,gBAAgB,CAAQ;IAChC,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,YAAY,CAAsB;IAC1C,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,oBAAoB,CAA8C;IAC1E,OAAO,CAAC,iBAAiB,CAA8C;gBAGrE,gBAAgB,EAAE,MAAM,EACxB,SAAS,GAAE,mBAAwB,EACnC,WAAW,CAAC,EAAE,MAAM;IAOtB;;OAEG;YACW,iBAAiB;IA6B/B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAO9B;;OAEG;IACH,OAAO,CAAC,cAAc;IAatB;;OAEG;IACH,OAAO,CAAC,aAAa;IAOrB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAO7B;;OAEG;IACH,OAAO,IAAI,IAAI;IAwHf,OAAO,CAAC,aAAa;IAiCrB,OAAO,CAAC,iBAAiB;IAiBzB;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,GAAG,GAAG,IAAI;IAMxB;;OAEG;IACH,qBAAqB,IAAI,OAAO;IAIhC;;OAEG;IACH,UAAU,IAAI,IAAI;CAoBnB"}