shell-mirror

# 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