shell-mirror 1.0.0

package/README.md

@@ -0,0 +1,272 @@
+# Shell Mirror
+
+A simple application to securely mirror your local computer's shell to a web browser on any device. It uses Google Authentication to ensure only you can access your shell session.
+
+## 🎯 Project Goal
+
+The primary goal is to allow a user to see their personal shell session (initially for macOS) running on their own computer, reflected in a web page accessible from their mobile phone or tablet. Access must be securely restricted to the user, leveraging a standard and robust authentication provider.
+
+Key objectives:
+- **Secure Mirroring**: Provide a real-time, read/write mirror of a user's shell.
+- **Robust Authentication**: Use Google OAuth 2.0 to ensure that only the owner can access the terminal session.
+- **Web-Based Access**: The web interface should allow a user to log in and connect to their running shell server.
+- **Simplicity**: The application should be a simple, standalone server that is easy to set up and run on a personal computer.
+
+---
+
+## 🗺️ Development Plan
+
+To achieve this vision, the project will be pivoted from its original, more complex architecture to a streamlined solution.
+
+### High-Level Plan
+
+1.  **Simplify the Architecture:**
+    *   **Remove Docker:** Eliminate all Docker-related files (`Dockerfile`, `docker-compose.yml`, etc.) and scripts. The application will run directly on the host machine.
+    *   **Remove Connection Broker:** The `broker.js` service is overly complex for the new goal and will be removed.
+
+2.  **Implement Robust Authentication:**
+    *   **Replace Custom Auth:** Swap the current manual token system (`auth.js`) with a standard, secure **Google OAuth 2.0** login flow using Passport.js.
+
+3.  **Refine the User Experience:**
+    *   **Login Page:** The web interface (`index.html`) will first present a "Login with Google" button.
+    *   **Secure Shell Access:** The shell view will only be loaded and connected *after* a successful login.
+
+---
+
+### Detailed Implementation Steps
+
+*   **Phase 1: Cleanup & Refactoring**
+    1.  Delete `Dockerfile`, `docker-compose.yml`, `docker-compose.override.yml`, and `.dockerignore`.
+    2.  Delete `broker.js`.
+    3.  Uninstall unused dependencies and remove Docker-related commands from `package.json`.
+    4.  Update `server.js` to remove all logic related to the broker and the old authentication system.
+
+*   **Phase 2: Google Authentication**
+    1.  Add new dependencies: `passport`, `passport-google-oauth20`, and `express-session`.
+    2.  Create a new `auth.js` to configure Passport for the Google login flow.
+    3.  Add the necessary login (`/auth/google`) and callback (`/auth/google/callback`) routes to `server.js`.
+    4.  Secure the WebSocket connection by ensuring the user is authenticated via their session.
+
+*   **Phase 3: Frontend UI**
+    1.  Modify `public/index.html` to conditionally show a "Login" button or the terminal.
+    2.  Add client-side logic to check the user's authentication status and initiate the WebSocket connection only when logged in.
+
+*   **Phase 4: Documentation**
+    1.  Update this `README.md` to reflect the new, simplified project goals, the plan outlined above, and provide clear instructions on how to set up and run the application, including how to generate Google OAuth credentials.
+
+---
+
+## 🚀 Getting Started
+
+### 1. Prerequisites
+
+- **Node.js**: Make sure you have Node.js (version 18 or higher) installed on your Mac.
+- **Google Account**: You will need a Google account to generate authentication credentials.
+
+### 2. Configure Google OAuth 2.0 Credentials
+
+Before you can run the application, you need to get a **Client ID** and **Client Secret** from the Google Cloud Console.
+
+1.  **Go to the Google Cloud Console**: [https://console.cloud.google.com/](https://console.cloud.google.com/)
+
+2.  **Create a new project** (or select an existing one).
+
+3.  **Enable the "Google People API"**: In the navigation menu, go to **APIs & Services > Library**, search for "Google People API", and click **Enable**.
+
+4.  **Configure the OAuth Consent Screen**:
+    *   Go to **APIs & Services > OAuth consent screen**.
+    *   Choose **External** and click **Create**.
+    *   Fill in the required fields (app name, user support email, developer contact).
+    *   On the "Scopes" page, you can leave it blank.
+    *   On the "Test users" page, add the Google account email you intend to log in with.
+
+5.  **Create Credentials**:
+    *   Go to **APIs & Services > Credentials**.
+    *   Click **+ CREATE CREDENTIALS** and select **OAuth client ID**.
+    *   For **Application type**, select **Web application**.
+    
+    **For Production (www.igori.eu):**
+    *   Under **Authorized JavaScript origins**, add `https://www.igori.eu`.
+    *   Under **Authorized redirect URIs**, add `https://www.igori.eu/auth/google/callback`.
+    
+    **For Local Development:**
+    *   Under **Authorized JavaScript origins**, add `http://localhost:3000`.
+    *   Under **Authorized redirect URIs**, add `http://localhost:3000/auth/google/callback`.
+    
+    *Note: You can add both production and development URLs to the same OAuth client.*
+    
+    *   Click **Create**. You will be shown your **Client ID** and **Client Secret**. Copy these.
+
+### 3. Configure the Application
+
+1.  **Create a `.env` file** in the root of the project by copying the example:
+    ```bash
+    cp .env.example .env
+    ```
+
+2.  **Edit the `.env` file** and add the credentials you just created:
+    
+    **For Production (www.igori.eu):**
+    ```
+    BASE_URL=https://www.igori.eu
+    PORT=3000
+    HOST=0.0.0.0
+    GOOGLE_CLIENT_ID=YOUR_GOOGLE_CLIENT_ID
+    GOOGLE_CLIENT_SECRET=YOUR_GOOGLE_CLIENT_SECRET
+    SESSION_SECRET=a-very-strong-and-long-random-string
+    ```
+    
+    **For Local Development:**
+    ```
+    BASE_URL=http://localhost:3000
+    PORT=3000
+    HOST=0.0.0.0
+    GOOGLE_CLIENT_ID=YOUR_GOOGLE_CLIENT_ID
+    GOOGLE_CLIENT_SECRET=YOUR_GOOGLE_CLIENT_SECRET
+    SESSION_SECRET=a-very-strong-and-long-random-string
+    ```
+    
+    *Replace the placeholder values with your actual credentials. Use a long, random string for the `SESSION_SECRET`.* 
+
+### 4. Install & Run
+
+1.  **Install dependencies**:
+    ```bash
+    npm install
+    ```
+
+2.  **Start the server**:
+    ```bash
+    npm start
+    ```
+
+### 5. Access Your Terminal
+
+**For Production:**
+- Open your web browser and go to `https://www.igori.eu`
+- You will be prompted to log in with your Google account
+- Once authenticated, you will see your shell mirrored in the browser
+
+**For Local Development:**
+- Open your web browser and go to `http://localhost:3000`
+- Or access from another device on the same network: `http://<your-macs-ip-address>:3000`
+- You will be prompted to log in with your Google account
+- Once authenticated, you will see your shell mirrored in the browser
+
+### 6. Deployment Notes
+
+**For Production Deployment:**
+- Ensure your server has SSL/TLS configured (required for HTTPS)
+- Set up proper firewall rules and security measures
+- Consider using a process manager like PM2 for production
+- Make sure the `BASE_URL` environment variable matches your actual domain
+
+**Environment Variables:**
+The application will validate that all required environment variables are set on startup and show helpful error messages if any are missing.
+
+### 7. Production Deployment
+
+**Automated Deployment to www.igori.eu:**
+
+The project includes an automated deployment script that uploads the application to the production server.
+
+```bash
+npm run deploy
+```
+
+**Deployment Process:**
+1. **Validation**: Checks that all required files exist and syntax is valid
+2. **Upload**: Securely uploads all application files via FTP
+3. **Verification**: Confirms all files were uploaded successfully
+4. **Instructions**: Displays post-deployment setup steps
+
+**Post-Deployment Setup:**
+After running the deployment script, you'll need to SSH into your server and:
+
+1. Install dependencies: `npm install`
+2. Configure environment: `cp .env.example .env` and edit with your Google OAuth credentials
+3. Start the server: `npm start` or `pm2 start server.js --name terminal-mirror`
+4. Set up reverse proxy (nginx) if needed for HTTPS
+
+**Security Notes:**
+- Ensure `.env` file has proper permissions (600)
+- Use a strong `SESSION_SECRET` (generate with: `openssl rand -hex 32`)
+- Keep Google OAuth credentials secure
+- Set up proper firewall rules
+
+---
+
+## 🛠️ Development Roadmap
+
+### Current Status ✅
+The application now has a solid foundation with:
+- Google OAuth 2.0 authentication implemented
+- Environment-based configuration for production/development
+- Basic shell mirroring via WebSocket
+- Secure session management
+
+### Next Development Phases
+
+#### Phase 1: Core Functionality Enhancement
+**Priority: High**
+- [ ] **WebSocket Authentication**: Secure WebSocket connections by validating user sessions
+- [ ] **Shell Session Management**: Implement proper shell session isolation per user
+- [ ] **Connection Resilience**: Add automatic reconnection logic for dropped WebSocket connections
+- [ ] **Error Handling**: Improve error handling for authentication failures and connection issues
+
+#### Phase 2: User Experience Improvements
+**Priority: Medium**
+- [ ] **Frontend UI Enhancement**: 
+  - Modernize the terminal interface (consider using xterm.js for better terminal emulation)
+  - Add login/logout UI states
+  - Implement loading states and connection indicators
+- [ ] **Shell Features**:
+  - Shell resizing support
+  - Copy/paste functionality
+  - Shell themes and customization
+- [ ] **Mobile Optimization**: Ensure the interface works well on mobile devices
+
+#### Phase 3: Security & Production Readiness
+**Priority: High for Production**
+- [ ] **Rate Limiting**: Add rate limiting for authentication and WebSocket connections
+- [ ] **Logging & Monitoring**: Implement structured logging and health check endpoints
+- [ ] **Session Security**: Add session timeout and secure session storage
+- [ ] **HTTPS/WSS**: Ensure all connections use secure protocols in production
+- [ ] **Environment Isolation**: Add development/staging/production environment configurations
+
+#### Phase 4: Advanced Features
+**Priority: Low (Future Enhancements)**
+- [ ] **Multi-Shell Support**: Allow multiple shell sessions per user
+- [ ] **File Upload/Download**: Add secure file transfer capabilities
+- [ ] **Shell Recording**: Save and replay shell sessions
+- [ ] **Collaboration Features**: Allow shared shell sessions (with proper security)
+- [ ] **Resource Monitoring**: Display system resource usage in the interface
+
+### Development Guidelines
+
+#### Code Structure
+- Keep `server.js` focused on server setup and routing
+- Use `auth.js` for all authentication logic
+- Create separate modules for shell management and WebSocket handling
+- Follow Node.js best practices for async/await and error handling
+
+#### Testing Strategy
+- Add unit tests for authentication logic
+- Implement integration tests for WebSocket functionality
+- Test OAuth flow in both development and production environments
+- Add automated security testing
+
+#### Deployment Considerations
+- Use PM2 or similar process manager for production
+- Implement proper logging with log rotation
+- Set up SSL/TLS certificates for HTTPS
+- Configure reverse proxy (nginx) if needed
+- Monitor application health and performance
+
+### Contributing
+When working on this project:
+1. Create feature branches for each development phase
+2. Test thoroughly in local environment before production
+3. Update this roadmap as features are completed
+4. Document any new environment variables in `.env.example`
+5. Keep security as the top priority for all changes

package/auth.js

@@ -0,0 +1,22 @@
+const passport = require('passport');
+const GoogleStrategy = require('passport-google-oauth20').Strategy;
+
+passport.use(new GoogleStrategy({
+    clientID: process.env.GOOGLE_CLIENT_ID,
+    clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+    callbackURL: `${process.env.BASE_URL}/auth/google/callback`
+  },
+  function(accessToken, refreshToken, profile, cb) {
+    // Here, you would typically find or create a user in your database.
+    // For this simple application, we'll just pass the profile through.
+    return cb(null, profile);
+  }
+));
+
+passport.serializeUser(function(user, cb) {
+  cb(null, user);
+});
+
+passport.deserializeUser(function(obj, cb) {
+  cb(null, obj);
+});

package/bin/shell-mirror

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+
+const { Command } = require('commander');
+const path = require('path');
+const fs = require('fs');
+const package = require('../package.json');
+
+// Import command modules
+const setupCommand = require('../lib/setup-wizard');
+const serverManager = require('../lib/server-manager');
+const configManager = require('../lib/config-manager');
+
+const program = new Command();
+
+program
+  .name('shell-mirror')
+  .description('Access your Mac shell from any device securely')
+  .version(package.version);
+
+// Setup command - Interactive OAuth configuration wizard
+program
+  .command('setup')
+  .description('Configure Google OAuth credentials and initialize Shell Mirror')
+  .option('-f, --force', 'Overwrite existing configuration')
+  .action(async (options) => {
+    try {
+      await setupCommand.run(options);
+    } catch (error) {
+      console.error('Setup failed:', error.message);
+      process.exit(1);
+    }
+  });
+
+// Start command - Launch the terminal server
+program
+  .command('start')
+  .description('Start the Shell Mirror server')
+  .option('-p, --port <port>', 'Port to run the server on', '3000')
+  .option('-h, --host <host>', 'Host to bind the server to', '0.0.0.0')
+  .option('-d, --daemon', 'Run as background daemon')
+  .action(async (options) => {
+    try {
+      await serverManager.start(options);
+    } catch (error) {
+      console.error('Failed to start server:', error.message);
+      process.exit(1);
+    }
+  });
+
+// Stop command - Stop the terminal server
+program
+  .command('stop')
+  .description('Stop the Shell Mirror server')
+  .action(async () => {
+    try {
+      await serverManager.stop();
+    } catch (error) {
+      console.error('Failed to stop server:', error.message);
+      process.exit(1);
+    }
+  });
+
+// Status command - Check server status
+program
+  .command('status')
+  .description('Check Shell Mirror server status')
+  .action(async () => {
+    try {
+      await serverManager.status();
+    } catch (error) {
+      console.error('Failed to check status:', error.message);
+      process.exit(1);
+    }
+  });
+
+// Config command - Manage configuration
+program
+  .command('config')
+  .description('Manage Shell Mirror configuration')
+  .option('--show', 'Show current configuration')
+  .option('--reset', 'Reset configuration to defaults')
+  .option('--set <key=value>', 'Set a configuration value')
+  .action(async (options) => {
+    try {
+      await configManager.manage(options);
+    } catch (error) {
+      console.error('Config management failed:', error.message);
+      process.exit(1);
+    }
+  });
+
+// Health command - Run health checks
+program
+  .command('health')
+  .description('Run health checks and diagnostics')
+  .action(async () => {
+    try {
+      const healthChecker = require('../lib/health-checker');
+      await healthChecker.run();
+    } catch (error) {
+      console.error('Health check failed:', error.message);
+      process.exit(1);
+    }
+  });
+
+// Install command - Post-install setup
+program
+  .command('install')
+  .description('Post-installation setup and verification')
+  .action(async () => {
+    try {
+      console.log('🎉 Shell Mirror installed successfully!');
+      console.log('');
+      console.log('Next steps:');
+      console.log('1. Run: shell-mirror setup');
+      console.log('2. Run: shell-mirror start');
+      console.log('3. Open your browser and visit the URL shown');
+      console.log('');
+      console.log('For help: shell-mirror --help');
+    } catch (error) {
+      console.error('Installation verification failed:', error.message);
+      process.exit(1);
+    }
+  });
+
+// Parse command line arguments
+program.parse();

package/lib/config-manager.js

@@ -0,0 +1,203 @@
+const fs = require('fs').promises;
+const path = require('path');
+const os = require('os');
+
+class ConfigManager {
+  constructor() {
+    this.configDir = path.join(os.homedir(), '.terminal-mirror');
+    this.configFile = path.join(this.configDir, 'config.json');
+    this.envFile = path.join(process.cwd(), '.env');
+  }
+
+  async manage(options = {}) {
+    if (options.show) {
+      await this.showConfig();
+    } else if (options.reset) {
+      await this.resetConfig();
+    } else if (options.set) {
+      await this.setConfig(options.set);
+    } else {
+      console.log('Configuration Management');
+      console.log('─'.repeat(30));
+      console.log('');
+      console.log('Usage:');
+      console.log('  terminal-mirror config --show     Show current configuration');
+      console.log('  terminal-mirror config --reset    Reset to defaults');
+      console.log('  terminal-mirror config --set key=value  Set a value');
+      console.log('');
+      console.log('Examples:');
+      console.log('  terminal-mirror config --set port=8080');
+      console.log('  terminal-mirror config --set baseUrl=https://example.com');
+    }
+  }
+
+  async showConfig() {
+    console.log('📋 Current Configuration');
+    console.log('─'.repeat(30));
+    console.log('');
+
+    // Load environment
+    require('dotenv').config({ path: this.envFile });
+
+    // Show main configuration
+    console.log('Environment Variables:');
+    const envVars = [
+      'BASE_URL',
+      'PORT', 
+      'HOST',
+      'NODE_ENV',
+      'GOOGLE_CLIENT_ID'
+    ];
+
+    envVars.forEach(key => {
+      const value = process.env[key];
+      if (key === 'GOOGLE_CLIENT_ID' && value) {
+        // Mask client ID for security
+        const masked = value.substring(0, 10) + '...' + value.substring(value.length - 10);
+        console.log(`  ${key}: ${masked}`);
+      } else {
+        console.log(`  ${key}: ${value || 'Not set'}`);
+      }
+    });
+
+    console.log('');
+    console.log('Secret Variables:');
+    console.log('  GOOGLE_CLIENT_SECRET: ' + (process.env.GOOGLE_CLIENT_SECRET ? '[SET]' : '[NOT SET]'));
+    console.log('  SESSION_SECRET: ' + (process.env.SESSION_SECRET ? '[SET]' : '[NOT SET]'));
+
+    // Show user config if exists
+    try {
+      const userConfig = JSON.parse(await fs.readFile(this.configFile, 'utf8'));
+      console.log('');
+      console.log('User Configuration:');
+      console.log(`  Setup Date: ${userConfig.setupDate || 'Unknown'}`);
+      console.log(`  Environment: ${userConfig.environment || 'Unknown'}`);
+    } catch (error) {
+      console.log('');
+      console.log('User Configuration: Not found');
+    }
+
+    // Show file locations
+    console.log('');
+    console.log('Configuration Files:');
+    console.log(`  Environment: ${this.envFile}`);
+    console.log(`  User Config: ${this.configFile}`);
+  }
+
+  async resetConfig() {
+    console.log('🗑️  Resetting Configuration');
+    console.log('');
+
+    const { confirm } = require('inquirer').prompt([{
+      type: 'confirm',
+      name: 'confirm',
+      message: 'This will delete all configuration. Continue?',
+      default: false
+    }]);
+
+    if (!(await confirm).confirm) {
+      console.log('Reset cancelled');
+      return;
+    }
+
+    try {
+      // Remove user config
+      try {
+        await fs.unlink(this.configFile);
+        console.log('✅ User configuration removed');
+      } catch (error) {
+        console.log('⚠️  User configuration not found');
+      }
+
+      // Remove .env file
+      try {
+        await fs.unlink(this.envFile);
+        console.log('✅ Environment file removed');
+      } catch (error) {
+        console.log('⚠️  Environment file not found');
+      }
+
+      // Remove PID and log files
+      const pidFile = path.join(this.configDir, 'server.pid');
+      const logFile = path.join(this.configDir, 'server.log');
+
+      try {
+        await fs.unlink(pidFile);
+      } catch (error) {
+        // Ignore
+      }
+
+      try {
+        await fs.unlink(logFile);
+      } catch (error) {
+        // Ignore
+      }
+
+      console.log('');
+      console.log('✅ Configuration reset complete');
+      console.log('Run "terminal-mirror setup" to reconfigure');
+
+    } catch (error) {
+      console.error('❌ Reset failed:', error.message);
+      throw error;
+    }
+  }
+
+  async setConfig(keyValue) {
+    const [key, value] = keyValue.split('=');
+    
+    if (!key || !value) {
+      console.error('❌ Invalid format. Use: key=value');
+      return;
+    }
+
+    console.log(`🔧 Setting ${key} = ${value}`);
+
+    try {
+      // Read current .env file
+      let envContent = '';
+      try {
+        envContent = await fs.readFile(this.envFile, 'utf8');
+      } catch (error) {
+        console.log('⚠️  .env file not found, creating new one');
+      }
+
+      // Update or add the key
+      const lines = envContent.split('\n');
+      let found = false;
+      const updatedLines = lines.map(line => {
+        if (line.startsWith(`${key}=`)) {
+          found = true;
+          return `${key}=${value}`;
+        }
+        return line;
+      });
+
+      if (!found) {
+        updatedLines.push(`${key}=${value}`);
+      }
+
+      // Write back to file
+      await fs.writeFile(this.envFile, updatedLines.join('\n'));
+      console.log('✅ Configuration updated');
+
+      // Update user config if applicable
+      if (['port', 'baseUrl'].includes(key)) {
+        try {
+          const userConfig = JSON.parse(await fs.readFile(this.configFile, 'utf8'));
+          userConfig[key] = value;
+          userConfig.lastModified = new Date().toISOString();
+          await fs.writeFile(this.configFile, JSON.stringify(userConfig, null, 2));
+        } catch (error) {
+          // User config doesn't exist, that's ok
+        }
+      }
+
+    } catch (error) {
+      console.error('❌ Failed to update configuration:', error.message);
+      throw error;
+    }
+  }
+}
+
+module.exports = new ConfigManager();