🔓 DEB Jailbreak Reader & Modifier

A professional, web-based tool for analyzing and modifying Debian package files (.deb), specifically designed for iOS jailbreak tweaks and packages.

✨ Features

• 🔍 Deep Package Analysis: Extract and view all contents of DEB files
• 📋 Package Information: Display comprehensive metadata and dependencies
• 📁 File Explorer: Navigate through package files with an intuitive tree view
• ✏️ File Editor: View and modify text files with syntax highlighting
• 💾 Repackage: Export modified DEB files ready for installation
• 🎨 Modern UI/UX: Beautiful, responsive interface with smooth animations
• ⚡ Fast Performance: Efficient parsing and file handling
• 🔒 Binary Support: Detect and handle binary files appropriately
• 🪟 Full Windows Support: Works natively on Windows with XZ compression support
• 📦 Cross-Platform: Pure JavaScript implementation with native module optimization

🖼️ Screenshots

Upload Interface

Drag and drop your DEB files with ease

Package Explorer

View package structure and metadata

File Editor

Edit files with syntax highlighting and live preview

🛠️ Technology Stack

Backend

• Node.js - Runtime environment
• Express - Web framework
• Multer - File upload handling
• ar-async - AR archive extraction (pure JavaScript)
• tar-stream - TAR archive processing
• lzma-native - XZ decompression (with Windows prebuilt binaries)
• Archiver - DEB file repackaging

Frontend

• React - UI framework
• React Dropzone - File upload interface
• React Icons - Icon library
• React Syntax Highlighter - Code highlighting
• Axios - HTTP client

📦 Installation

⭐ NEW: Installation System v2.0

We've completely rewritten the installation system for maximum reliability!

Features:

• ✅ PowerShell-based installer with retry logic
• ✅ Automatic error recovery
• ✅ Better diagnostics and error messages
• ✅ Fallback installation methods
• ✅ Comprehensive verification

📋 For complete installation instructions, troubleshooting, and advanced topics, see INSTALLATION_GUIDE.md

Prerequisites

• Node.js (v18.0.0 or higher)
• npm (comes with Node.js)

Download Node.js from: https://nodejs.org/

Windows Installation

Quick Start (Recommended):

1. Clone or download this repository

   git clone <repository-url>
   cd jailbreak

2. Run the installer (double-click or run from command prompt)

   install.bat

   This will automatically:

   • Test npm connectivity
   • Install all dependencies with retry logic
   • Verify all packages are installed correctly
   • Provide detailed error messages if anything fails

Alternative Methods:

If the PowerShell installer has issues, try:

# Batch-only fallback installer
install-batch-fallback.bat

# Or fix broken dependencies
fix-dependencies.bat

Note: Modern DEB files use XZ compression. The installer will set up lzma-native with prebuilt binaries for Windows.

🎯 Windows Scripts Overview

Script	Purpose	When to Use
QUICK_START.bat	Install + Launch	First time setup
install.bat	Install dependencies (PowerShell)	Manual installation (recommended)
install-batch-fallback.bat	Install dependencies (Batch only)	If PowerShell fails
start.bat	Launch application	Normal usage
stop.bat	Stop all services	Shutdown
diagnose.bat	System diagnostic	Check system status
fix-dependencies.bat	Fix broken dependencies	Installation problems

📋 For detailed information about each script, see WINDOWS_SCRIPTS_GUIDE.md

Linux/Mac Installation

1. Install dependencies

   npm run install-all

🚀 Usage

Windows

Method 1: Quick Start (Recommended for first-time users)

QUICK_START.bat

Double-click QUICK_START.bat - it will install dependencies and launch everything automatically!

Method 2: Manual Launch

start.bat

Double-click start.bat to launch the application (requires dependencies to be installed first)

Method 3: Stop Application

stop.bat

Double-click stop.bat to stop all running services

Features:

• ✅ No need for concurrently package
• ✅ Launches backend and frontend in separate color-coded windows
• ✅ Automatic browser opening
• ✅ Auto-installation if dependencies are missing
• ✅ Visual progress indicators
• ✅ Easy troubleshooting

Linux/Mac

npm start

Access the Application

Once started, the application will be available at:

• Frontend: http://localhost:3000
• Backend API: http://localhost:5000

Your default browser will automatically open to the frontend.

📖 How to Use

1. Upload a DEB File

• Drag and drop a .deb file onto the upload area
• Or click to browse and select a file
• Wait for the file to be processed

Example file: com.bandarhl.bhtwitter_4.4-1+debug_iphoneos-arm64.deb

2. Explore Package Information

• View package metadata (name, version, author, etc.)
• Check dependencies
• See installed size and architecture

3. Navigate Files

• Use the file explorer to browse the package contents
• Click on folders to expand/collapse
• Click on files to view their contents

4. Edit Files

• Select a file from the explorer
• Click the "Edit" button
• Make your changes
• Click "Save" to apply changes

5. Download Modified Package

• After making changes, click "Download Modified DEB"
• Your browser will download the repackaged DEB file
• The file is ready for installation

🔧 API Endpoints

Upload DEB File

POST /api/upload
Content-Type: multipart/form-data

Get File Information

GET /api/file/:fileId

Get File Content

GET /api/file/:fileId/content/:filePath

Update File Content

POST /api/file/:fileId/content/:filePath
Content-Type: text/plain

Repackage DEB

POST /api/file/:fileId/repackage

List All Files

GET /api/files

Delete File

DELETE /api/file/:fileId

📁 Project Structure

jailbreak/
├── client/                 # React frontend
│   ├── public/
│   │   └── index.html
│   ├── src/
│   │   ├── components/     # React components
│   │   │   ├── Header.js
│   │   │   ├── FileUpload.js
│   │   │   ├── PackageInfo.js
│   │   │   ├── FileExplorer.js
│   │   │   └── FileEditor.js
│   │   ├── App.js          # Main app component
│   │   ├── App.css
│   │   ├── index.js
│   │   └── index.css
│   └── package.json
├── server/                 # Node.js backend
│   ├── index.js            # Express server
│   ├── debParser.js        # DEB parsing logic
│   ├── uploads/            # Uploaded files (generated)
│   ├── extracted/          # Extracted contents (generated)
│   └── package.json
├── install.bat             # Windows installer
├── start.bat               # Windows launcher
├── package.json            # Root package file
└── README.md

🎨 Customization

Changing Ports

Edit server/index.js:

const PORT = process.env.PORT || 5000; // Change 5000 to your port

Edit client/package.json:

"proxy": "http://localhost:5000" // Update to match server port

Styling

All component styles are in their respective .css files in client/src/components/

Main app styles: client/src/App.css

🐛 Troubleshooting

🚨 HAVING PROBLEMS? → See TROUBLESHOOTING.md for complete troubleshooting guide

Quick Fixes

❌ "Cannot find module 'express'" or similar errors

This is the most common issue! It means dependencies weren't installed correctly.

Quick Fix (Windows):

fix-dependencies.bat

This will clean everything and reinstall all dependencies fresh.

Manual Fix:

1. Delete node_modules, server\node_modules, and client\node_modules folders
2. Run install.bat

🔍 Check System Status

Run diagnostic to see what's wrong:

diagnose.bat

Windows Users

📋 See WINDOWS_INSTALL.md for comprehensive Windows troubleshooting guide

Common Windows issues:

• Missing dependencies (Express, React, etc.) → Run fix-dependencies.bat
• Build tools missing (lzma-native installation) → Usually optional, app will still work
• XZ decompression errors → Install with npm install --global windows-build-tools
• Permission issues → Run scripts as Administrator
• Port conflicts → Run stop.bat to kill existing processes

Port Already in Use

If you see "Port 3000 or 5000 is already in use":

stop.bat

Or manually kill processes:

netstat -ano | findstr :5000
taskkill /PID <PID> /F

Dependencies Not Installing

First try the fix script (Windows):

fix-dependencies.bat

Manual approach:

npm cache clean --force
npm install

For Windows users having trouble with native modules:

npm install --build-from-source=false

DEB File Not Parsing

Make sure:

• File is a valid .deb file
• File is not corrupted
• File has proper permissions
• XZ compression is supported (requires lzma-native)

Supported compression formats:

• ✅ Gzip (.tar.gz)
• ✅ XZ (.tar.xz) - Requires lzma-native
• ✅ Uncompressed (.tar)

🔒 Security Notes

• This tool is designed for educational and development purposes
• Always verify package contents before installation
• Be cautious when installing modified packages on production devices
• Keep backups of original DEB files

📝 License

MIT License - feel free to use this project for any purpose

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📧 Support

For issues and questions, please open an issue on GitHub.

🌟 Acknowledgments

• Built with love for the jailbreak community
• Inspired by the need for better DEB package management tools
• Thanks to all open-source contributors whose libraries made this possible

---

Made with ❤️ for iOS Jailbreak Developers

🔓 Happy Hacking!

Contributing

Contributions are welcome. Read CONTRIBUTING.md and use the issue templates. Good first contributions include sanitized DEB fixtures, path-traversal tests, accessibility improvements, and cross-platform diagnostics.

Security

Report vulnerabilities privately as described in SECURITY.md.

License

Released under the MIT License.