git/tustu
1
0
Fork 0
mirror of https://github.com/johndoe6345789/tustu.git synced 2026-04-24 13:45:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

Refactor documentation and consolidate scripts

Browse Source 
- Deleted `IMPLEMENTATION_SUMMARY.md` as its content is now integrated into other documentation.
- Added `INDEX.md` for quick navigation of the scripts folder.
- Created `MARKDOWN_STYLE.md` to establish a consistent markdown style guide for documentation.
- Updated `README.md` to reflect the new documentation structure and provide links to additional resources.
- Introduced `README_SCRIPTS.md` detailing the consolidation of scripts into `tustu_tools.py`.
- Added `REORGANIZATION_SUMMARY.md` to summarize the changes made during the scripts reorganization.
- Removed `TEST_DATA_GENERATOR_FEATURE.md` as its content is now covered in `README_SCRIPTS.md`.
- Updated `scripts/README.md` to include links to new documentation files and improve clarity.
This commit is contained in:
johndoe6345789
2026-01-11 21:09:51 +00:00
parent db8eac5a02
commit 89317fbc21
10 changed files with 22 additions and 882 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/.markdownlint.json Normal file
View File

@@ -0,0 +1,6 @@
{
"default": true,
"MD013": false,
"MD033": false,
"MD041": false
}

141
docs/EMAIL_GENERATION_FEATURE.md
View File

@@ -1,141 +0,0 @@
# Email Generation Feature
## Summary
Added email generation functionality to the Email Parser tab in `registration_gui.py`.
## Changes Made
### 1. UI Updates
- Added "Generate Email Format" button (green, positioned between Parse and Copy buttons)
- Made all output fields **editable** (removed `setReadOnly(True)`)
- Added placeholder text to guide users on manual entry
- Updated instructions to explain both Parse and Generate modes
### 2. New Functionality: `generate_email()` Method
**Location**: `registration_gui.py`, EmailParserTab class
**Purpose**: Generate registration email format from field values
**Behavior**:
1. Reads values from output fields (first name, last name, email, serial, key)
2. Validates that required fields are filled
3. Generates formatted text matching MegaLogViewer's expected format:
```
[Registration]
First Name: <value>
Last Name: <value>
Registered email: <value>
Serial Number: <value> (optional, if provided)
Registration Key: <value>
[End Registration]
```
4. Displays formatted text in the email text area
5. Automatically copies to clipboard
6. Shows success message
### 3. Workflow Support
The Email Parser tab now supports **three modes**:
#### Mode 1: Parse (Original)
User pastes registration email → Click "Parse Email" → Fields populated
#### Mode 2: Generate (New)
User fills fields manually → Click "Generate Email Format" → Formatted email created
#### Mode 3: Round-trip (Combined)
Generate key on another tab → Switch to Email tab → Manually enter info → Generate email → Send to user → User pastes email → Parse validates
### 4. Implementation Details
**Java Analysis**:
- Analyzed `com/efiAnalytics/ui/dS.java` (registration dialog)
- Found email **parsing** logic (lines 210-232)
- No email **generation** code exists in Java app
- Java app only accepts pasted emails, doesn't create them
**Python Implementation**:
- Created `generate_email()` method based on observed format
- Follows exact field names and structure from parser
- Handles optional Serial Number field
- Provides clipboard integration for easy sharing
### 5. Testing
Created `test_email_generation.py` demonstrating:
- Generation with serial number
- Generation without serial number
- Correct format matching parse expectations
**Test Results**: ✓ All tests passing
### 6. Documentation
Updated `README.md` with:
- Email Parser tab capabilities
- Parse vs Generate mode descriptions
- Validation workflow
- Usage examples
- Requirements
## Usage Example
### Scenario: Creating a registration email to send to a user
1. Open the GUI: `python3 registration_gui.py`
2. Generate a key on any generation tab (Basic, 5-param, etc.)
3. Switch to "Email Parser" tab
4. Enter the user's information:
- First Name: John
- Last Name: Doe
- Email: john.doe@example.com
- Registration Key: (paste generated key)
- Serial Number: ABC123 (optional)
5. Click "Generate Email Format"
6. Formatted email appears in text area AND is copied to clipboard
7. Paste into email client and send to user
### Scenario: Validating a received registration
1. User sends you their registration info via email
2. Open GUI → Email Parser tab
3. Paste their email into text area
4. Click "Parse Email"
5. Click "Validate Key" to check correctness
6. Provide product name and secret when prompted
7. See validation result (valid/invalid)
## Files Modified
- `registration_gui.py`: Added generate_email() method, made fields editable, updated UI
- `README.md`: Documented new features and workflows
- Created `test_email_generation.py`: Demonstration script
## Technical Notes
**Format Specification**:
- Marker: `[Registration]` (start) and `[End Registration]` (end)
- Fields: `Field Name: Value` format, one per line
- Field names must match exactly: "First Name:", "Last Name:", "Registered email:", etc.
- Serial Number is optional
- Registration Key can be multi-line (parser handles this)
**Clipboard Integration**:
- Uses `QApplication.clipboard()` for cross-platform support
- Automatically copies generated email for convenience
- User doesn't need to manually select and copy
**Error Handling**:
- Validates required fields before generation
- Shows warning if first name, last name, email, or key missing
- Serial number is optional (skipped if empty)
## Benefits
1. **Completeness**: Email tab now handles both directions (parse ← → generate)
2. **Workflow**: Enables creating registration emails to send to users
3. **Convenience**: Automatic clipboard copy saves steps
4. **Consistency**: Format exactly matches what parser expects
5. **User-Friendly**: Clear instructions and error messages

261
docs/IMPLEMENTATION_SUMMARY.md
View File

@@ -1,261 +0,0 @@
# Implementation Summary: Test Data Generator
## What Was Implemented
Added **automatic test data generation** to the Registration GUI with "Load Test Data" buttons on all tabs. The system generates realistic dummy credentials AND **mathematically valid registration keys** that pass validation.
## Key Features
### 1. Realistic Test Data
- **32 first names**: James, Mary, Robert, Jennifer, etc.
- **32 last names**: Smith, Johnson, Williams, Brown, etc.
- **10 email domains**: gmail.com, yahoo.com, company.com, etc.
- **3 products**: MegaLogViewer, TunerStudio, DataLogger
- **4 secrets**: secret123, testkey, demo2024, abc123xyz
- **6 serial numbers**: SN001, ABC123, XYZ789, DEV001, TEST99
### 2. Valid Registration Keys
**Critical Feature**: Keys are NOT random - they're generated using the actual algorithm!
```python
# EmailParserTab automatically generates VALID keys
key = RegistrationKeyGenerator.generate_key_5param(
first_name, last_name, product, secret, email
)
# This key WILL pass validation with the correct product/secret
```
### 3. UI Integration
#### All Generation Tabs (Basic, 5-param, 7-param, 8-param)
- **Blue "Load Test Data" button** (left of Generate button)
- Populates all input fields
- Shows popup with generated data
- User then clicks "Generate Key" → "Validate Key" → ✓ Valid!
#### Email Parser Tab
- **Purple "Load Test Data" button** (left of Parse button)
- Populates all fields INCLUDING a pre-generated valid key
- Shows popup with product/secret for validation testing
- User can immediately click "Validate Key" or "Generate Email"
## Java Compatibility Verified
Reviewed Java source code to ensure generated keys are accepted:
### Character Sets Match
```java
// Java (C0997e.java)
"123456789ABCDEFGHIJKLMNPQRSTUVWXYZ" // Basic
"23456789ABCDEFGHJKLMNPQRSTUVWXYZ" // Enhanced (no 1, I, O)
// Python (registration_gui.py)
CHARSET_BASIC = "123456789ABCDEFGHIJKLMNPQRSTUVWXYZ"
CHARSET_ENHANCED = "23456789ABCDEFGHJKLMNPQRSTUVWXYZ"
```
### Validation Logic Matches
```java
// Java (dS.java line 297)
if (str2.equals(strTrim4)) { // Exact string comparison
// Valid registration
}
// Python
if expected_key == reg_key: # Exact string comparison
# Valid registration
```
### MD5 Hashing Identical
Both implementations:
- Use MD5 MessageDigest
- Apply multiple hash rounds (double update)
- Use same byte manipulation
- Produce identical output
**Result**: Generated test keys will be accepted by the actual Java application.
## Files Modified
1. **registration_gui.py**:
- Added `DummyDataGenerator` class (lines 18-84)
- Added `import random` for random selection
- Added `load_test_data()` method to `KeyGeneratorTab` class
- Added "Load Test Data" button to `KeyGeneratorTab` button layout
- Added `load_test_data()` method to `EmailParserTab` class
- Added "Load Test Data" button to `EmailParserTab` button layout
2. **Documentation**:
- Created `TEST_DATA_GENERATOR_FEATURE.md` - Comprehensive feature documentation
- Created `test_dummy_data.py` - Test suite demonstrating functionality
- Created `demo_test_data_ui.py` - Visual UI workflow demonstration
- Updated `README.md` - Added Test Data Generator section
## Usage Examples
### Quick Test Workflow
```bash
# 1. Launch GUI
python3 registration_gui.py
# 2. On any tab, click "Load Test Data" (blue/purple button)
# 3. Click "Generate Registration Key"
# 4. Click "Validate Key"
# Result: ✓ Valid Registration
```
### Email Parser Complete Workflow
```bash
# 1. Go to Email Parser tab
# 2. Click purple "Load Test Data"
# 3. Note the product and secret in the popup (e.g., MegaLogViewer, secret123)
# 4. Click "Generate Email Format" → Email created and copied
# 5. Click "Validate Key"
# 6. Enter product="MegaLogViewer", secret="secret123"
# Result: ✓ Valid Registration
```
### Round-Trip Testing
```bash
# 1. Generate tab: Load test data → Generate key → Copy
# 2. Email tab: Load test data → Paste key → Generate email
# 3. Parse tab: Paste email → Parse → Validate
# Result: Full workflow validated end-to-end
```
## Testing Results
All tests passing:
### Test 1: Data Generation ✓
```
Generated 5 random test sets
Each with valid registration keys
All fields populated correctly
```
### Test 2: Validation ✓
```
Tested all 4 algorithms (4/5/7/8-parameter)
Keys are deterministic (same input → same output)
Keys pass validation consistently
```
### Test 3: Email Format ✓
```
Generated properly formatted registration emails
Format matches Java parser expectations
Round-trip works (generate → parse → validate)
```
### Integration Test ✓
```python
data = DummyDataGenerator.generate()
key = RegistrationKeyGenerator.generate_key_5param(...)
key2 = RegistrationKeyGenerator.generate_key_5param(...) # Same inputs
assert key == key2 # ✓ Deterministic
```
## Benefits
1. **Speed**: No manual typing - one click to fill all fields
2. **Accuracy**: Keys are mathematically valid, not random
3. **Variety**: Random selection ensures different test cases
4. **Realism**: Names and emails look authentic
5. **Reproducibility**: Fixed secrets allow predictable testing
6. **Education**: Popups guide users on next steps
7. **Validation**: Can immediately test the full validation workflow
8. **Development**: Saves hours during testing and debugging
## Security Notes
**Test Data Only**: The fixed secrets (secret123, testkey, etc.) are for testing purposes. Production systems should use:
- Cryptographically secure random secret generation
- Per-customer unique secrets
- Proper key management and storage
- Time-limited or hardware-locked licenses
## Python Packages Required
No new dependencies! Uses only:
- `random` (Python standard library) - for random selection
- `hashlib` (Python standard library) - for MD5 hashing
- `PyQt6` (already required) - for GUI
## Command Line Testing
```bash
# Test data generation
python3 test_dummy_data.py
# Visual UI demo
python3 demo_test_data_ui.py
# Quick integration test
python3 -c "
from registration_gui import DummyDataGenerator, RegistrationKeyGenerator
data = DummyDataGenerator.generate()
key = RegistrationKeyGenerator.generate_key_5param(
data['first_name'], data['last_name'], data['product'],
data['secret'], data['email']
)
print(f'Name: {data[\"first_name\"]} {data[\"last_name\"]}')
print(f'Key: {key}')
"
```
## Visual Example
```
┌─ 5-Parameter Tab ────────────────────────────┐
│ │
│ First Name: [ ] │
│ Last Name: [ ] │
│ Product: [ ] │
│ Secret: [ ] │
│ Email: [ ] │
│ │
│ [Load Test Data] [Generate Key] [Validate] │
│ │
└──────────────────────────────────────────────┘
↓ Click "Load Test Data"
┌─ 5-Parameter Tab ────────────────────────────┐
│ │
│ First Name: [ John ] │
│ Last Name: [ Smith ] │
│ Product: [ MegaLogViewer ] │
│ Secret: [ secret123 ] │
│ Email: [ john.smith@gmail.com ] │
│ │
│ [Load Test Data] [Generate Key] [Validate] │
│ │
└──────────────────────────────────────────────┘
↓ Click "Generate Key"
┌─ Generated Key ──────────────────────────────┐
│ ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ │
│ ┃ ABCD1234EFGH5678IJKL9012 ┃ │
│ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ │
└──────────────────────────────────────────────┘
↓ Click "Validate"
┌─ Validation Result ──────────────────────────┐
│ ✓ Valid Registration │
│ │
│ Registered to: │
│ Name: John Smith │
│ Email: john.smith@gmail.com │
│ Product: MegaLogViewer │
└──────────────────────────────────────────────┘
```
## Conclusion
✓ Feature complete and tested
✓ Keys are mathematically valid
✓ Java compatibility verified
✓ Documentation complete
✓ No additional dependencies
✓ Works on all 5 tabs
✓ Saves significant testing time
✓ Provides realistic test scenarios
The GUI now has a professional test data generator that makes testing fast, easy, and reliable!

68
docs/INDEX.md Normal file
View File

@@ -0,0 +1,68 @@
# Scripts Folder - Quick Index
Quick navigation guide for the scripts folder.
## 🎯 What You Need
| I want to... | Go to... |
|--------------|----------|
| Generate registration keys, test data, or use tools | `tustu_tools.py` - [Documentation](TUSTU_TOOLS_README.md) |
| Understand the folder organization | [README_SCRIPTS.md](README_SCRIPTS.md) |
| Access original scripts | [legacy/](legacy/) folder - [Details](legacy/README.md) |
| View analysis data | [data/](data/) folder - [Details](data/README.md) |
## 📖 Documentation Files
| File | Purpose |
|------|---------|
| `README.md` | Quick overview and examples |
| `README_SCRIPTS.md` | Detailed migration guide |
| `TUSTU_TOOLS_README.md` | Complete tool documentation |
| `INDEX.md` | This file (quick navigation) |
## 🔧 Main Tool
**File:** `tustu_tools.py`
**Quick Commands:**
```bash
python3 tustu_tools.py --help # Show all commands
python3 tustu_tools.py gen-key -t # Generate key with test data
python3 tustu_tools.py test-data -n 5 # Generate 5 test sets
python3 tustu_tools.py gui # Launch GUI
```
**From project root:**
```bash
./tustu-tools --help
./tustu-tools gen-key --test-data
```
## 📂 Folder Contents
### Main Files (scripts/)
- ⭐ `tustu_tools.py` - Unified command-line tool
- 📖 `*.md` - Documentation files
### legacy/
- All original individual Python scripts
- Preserved for reference
- See [legacy/README.md](legacy/README.md)
### data/
- JSON mapping and analysis files
- Generated data files
- See [data/README.md](data/README.md)
## 🚦 Getting Started
1. **First time?** Start with [README.md](README.md)
2. **Need examples?** Check [TUSTU_TOOLS_README.md](TUSTU_TOOLS_README.md)
3. **Migrating code?** Read [README_SCRIPTS.md](README_SCRIPTS.md)
## 🔗 Quick Links
- [Complete Documentation](TUSTU_TOOLS_README.md)
- [Legacy Scripts Info](legacy/README.md)
- [Data Files Info](data/README.md)
- [Project Root](../)

129
docs/MARKDOWN_STYLE.md Normal file
View File

@@ -0,0 +1,129 @@
# Markdown Style Guide
This document describes the markdown style used in the scripts folder documentation.
## Conventions
### Headers
- Use ATX-style headers (`#` prefix)
- Add blank line before and after headers
- Use sentence case for titles
### Code Blocks
- Always specify language for syntax highlighting
- Use \`\`\`bash for shell commands
- Use \`\`\`python for Python code
- Use inline \` for command names and file names
### Lists
- Use `-` for unordered lists
- Add blank line before and after lists
- Use consistent indentation (2 spaces)
### Tables
- Use pipes (`|`) for table formatting
- Add header separator row
- Align columns for readability
- Keep tables simple (max 3-4 columns)
### Emphasis
- Use `**bold**` for important terms
- Use `*italic*` for emphasis
- Use `code` for technical terms
- Use > for blockquotes/callouts
### Links
- Use relative links within project
- Use descriptive link text
- Format: `[text](path/to/file.md)`
### Emojis
Used sparingly for visual organization:
- 🎯 Goals/objectives
- ✅ Completed items
- ⭐ Important/featured
- 📖 Documentation
- 💾 Data/storage
- 📦 Archives/legacy
- 🚀 Quick start
- <20><>️ Tools
- 📁 File structure
## File Types
### INDEX.md
- Quick navigation only
- Table format for clarity
- Links to all major sections
### README.md
- Brief overview
- Quick start examples
- Links to detailed docs
### README_SCRIPTS.md
- Detailed migration guide
- Before/after comparisons
- Complete command reference
### TUSTU_TOOLS_README.md
- Complete tool documentation
- All commands with examples
- Full reference guide
## Example Patterns
### Command Reference Table
\`\`\`markdown
| Command | Description |
|---------|-------------|
| \`command\` | What it does |
\`\`\`
### Quick Start Section
\`\`\`markdown
## Quick Start
\`\`\`bash
./command --option
\`\`\`
\`\`\`
### File Structure
\`\`\`markdown
folder/
├── file1.py # Description
├── file2.md # Description
└── subfolder/ # Description
\`\`\`
## Validation
Files follow these principles:
1. **Clear hierarchy** - Logical header structure
2. **Scannable** - Use tables and lists
3. **Consistent** - Same patterns throughout
4. **Actionable** - Clear examples
5. **Linked** - Easy navigation
## Maintenance
When adding content:
- Match existing style
- Update table of contents if present
- Test all links
- Check code examples work
- Keep line length reasonable

246
docs/README.md
View File

@@ -1,236 +1,26 @@
# Registration Key Algorithm
# Additional Documentation
This document describes the registration key generation algorithm found in `app/bH/f.java` (previously `app/src/main/java/bH/C0997e.java`).
This folder contains supplementary documentation for the scripts folder.
## Overview
## Files
The algorithm generates registration keys for product licensing using a multi-step process that combines user information, applies various transformations, and generates a cryptographic hash.
| File | Purpose |
|------|---------|
| **INDEX.md** | Quick navigation index for all documentation |
| **README_SCRIPTS.md** | Detailed migration guide from individual scripts |
| **REORGANIZATION_SUMMARY.md** | Summary of folder reorganization |
| **MARKDOWN_STYLE.md** | Markdown style guide for documentation |
## Algorithm Steps
## Main Documentation
### Method 1: Basic Obfuscation
`a(String str, String str2, String str3, String str4)`
For everyday use, refer to the main documentation:
Parameters:
- `str` - First name
- `str2` - Last name
- `str3` - Product name
- `str4` - Email address
- **[../README.md](../README.md)** - Scripts folder overview
- **[../TUSTU_TOOLS_README.md](../TUSTU_TOOLS_README.md)** - Complete tool reference
**Process:**
## When to Read These Files
1. **Input Validation** - Check all parameters are non-null and non-empty
2. **Concatenation** - Create byte array by concatenating:
```
lastName + productName + firstName + lastName + email
```
3. **Byte Reversal** - Reverse the entire byte array
```java
for (int i = 0; i < bArr.length / 2; i++) {
byte temp = bArr[i];
bArr[i] = bArr[(bArr.length - 1) - i];
bArr[(bArr.length - 1) - i] = temp;
}
```
4. **Character Transformation** - Apply mathematical formula to each byte:
```java
for (int i = 0; i < bArr.length; i++) {
byte b = bArr[i];
int transformed = (b + ((b - 32) % 7)) - (i % 4);
if (transformed > 122) {
transformed -= 9;
}
bArr[i] = (byte) transformed;
}
```
5. **Special Character Handling** - Modify specific ASCII codes:
```java
for (int i = 0; i < bArr.length; i++) {
if (bArr[i] == 96 || bArr[i] == 92 || bArr[i] == 91 ||
bArr[i] == 93 || bArr[i] == 59 || bArr[i] == 46) {
bArr[i] = (byte) (bArr[i] + 6 + (i % 10));
}
}
```
Special characters affected: `` ` `` (96), `\` (92), `[` (91), `]` (93), `;` (59), `.` (46)
6. **Return** - Convert byte array to string
### Method 2: Registration Key Generation (5 Parameters)
`a(String str, String str2, String str3, String str4, String str5)`
Parameters:
- `str` - First name
- `str2` - Last name
- `str3` - Product name
- `str4` - Secret/seed value
- `str5` - Email address
**Process:**
1. **Get Obfuscated String** - Call Method 1 to get obfuscated base string
2. **MD5 Hashing** - Create MD5 hash:
```java
MessageDigest md5 = MessageDigest.getInstance("MD5");
byte[] input = (obfuscatedString + secret).getBytes();
md5.update(input);
md5.update(input); // Update twice
md5.digest(); // Digest once (discarded)
md5.update(input); // Update again
byte[] hash = md5.digest(); // Final digest
```
3. **Checksum Generation** - Create 4-byte checksum using custom algorithm
4. **Combine Checksum and Hash**:
```
result = checksum (4 bytes) + hash (16 bytes) = 20 bytes total
```
5. **Base-32 Encoding** - Convert to custom base-32 string:
```
Charset: "123456789ABCDEFGHIJKLMNPQRSTUVWXYZ" (33 characters, no 'O')
```
Each byte is mapped to a character: `char = charset[abs(byte) % 33]`
### Method 3: Enhanced Registration Key (7 Parameters)
`a(String str, String str2, String str3, String str4, String str5, String str6, String str7)`
Additional parameters:
- `str6` - Additional field 1
- `str7` - Additional field 2
**Changes from Method 2:**
1. **Lowercase Conversion** - firstName, lastName, and email are converted to lowercase
2. **Extended Base String**:
```
obfuscated(firstName.toLowerCase(), lastName.toLowerCase(), product, email.toLowerCase()) + field1 + field2
```
3. **Modified MD5 Process**:
```java
md5.update(input);
md5.update(input);
md5.update((input + field1).getBytes()); // Additional update with field1
byte[] hash = md5.digest();
```
4. **Different Character Set**:
```
Charset: "23456789ABCDEFGHJKLMNPQRSTUVWXYZ" (31 characters, no '1', 'I', 'O')
char = charset[abs(byte) % 31]
```
### Method 4: Full Registration Key (8 Parameters)
`a(String str, String str2, String str3, String str4, String str5, String str6, String str7, String str8)`
Additional parameter:
- `str8` - Additional field 3
**Changes:**
- Base string includes all three additional fields: `field1 + field2 + field3`
- Same character set as Method 3
## Usage Context
The registration dialog calls these methods (found in `app/src/main/java/ao/dQ.java`):
```java
String calculatedKey = C0997e.a(firstName, lastName, "MegaLogViewer", email);
if (calculatedKey != null && calculatedKey.equals(userEnteredKey) && !alreadyRegistered(userEnteredKey)) {
// Registration successful
}
```
## Key Properties
- **Character Sets**: Custom base-32 encoding (excludes ambiguous characters like 'O', '1', 'I')
- **Output Length**: 20 characters (from 20 bytes)
- **Hash Algorithm**: MD5
- **Deterministic**: Same inputs always produce same key
- **Case Handling**: Methods 3 & 4 normalize to lowercase for consistency
## Security Notes
- Uses MD5 hashing (considered weak by modern standards)
- Obfuscation through byte manipulation
- No salt/random component (deterministic output)
- Multiple hash iterations for additional complexity
- Custom encoding prevents simple reverse engineering
## GUI Application
The PyQt6 GUI (`registration_gui.py`) provides an intuitive interface for:
### Key Generation
- **Basic Tab**: 4-parameter algorithm (first name, last name, product, email)
- **5-Parameter Tab**: Standard algorithm with secret key
- **7-Parameter Tab**: Enhanced algorithm with date fields (month, year)
- **8-Parameter Tab**: Full algorithm with serial number support
### Email Parser Tab
The Email Parser tab provides bi-directional functionality:
#### Parse Mode
- Paste a registration email in `[Registration]...[End Registration]` format
- Click "Parse Email" to extract:
- First Name
- Last Name
- Email Address
- Serial Number (if present)
- Registration Key
#### Generate Mode
- Manually enter or edit registration information in the fields
- Click "Generate Email Format" to create formatted registration text
- The generated email is automatically:
- Displayed in the text area
- Copied to clipboard
- Format matches MegaLogViewer's expected structure:
```
[Registration]
First Name: John
Last Name: Doe
Registered email: john.doe@example.com
Serial Number: ABC123
Registration Key: XYZ789...
[End Registration]
```
#### Test Data Generator
- Click **"Load Test Data"** button on any tab (blue/purple button)
- Automatically populates fields with realistic dummy data
- Generates **valid registration keys** that pass validation
- Includes first/last names, emails, products, secrets, and serials
- EmailParser tab: generates complete set including valid key
- Saves time during testing and development
**Available Test Data**:
- 32 first names (James, Mary, Robert, Jennifer, etc.)
- 32 last names (Smith, Johnson, Williams, etc.)
- 10 email domains (gmail.com, company.com, etc.)
- 3 products: MegaLogViewer, TunerStudio, DataLogger
- 4 secrets: secret123, testkey, demo2024, abc123xyz
- 6 serial numbers: SN001, ABC123, XYZ789, etc.
**Validation Guarantee**: Keys generated with test data are mathematically valid and will pass validation using the correct product/secret combination.
```
### Requirements
- Python 3.6+
- PyQt6 6.6.0+
Install dependencies:
```bash
pip install PyQt6
```
- **New contributors** - Read MARKDOWN_STYLE.md for documentation standards
- **Migrating code** - Read README_SCRIPTS.md for detailed migration info
- **Understanding history** - Read REORGANIZATION_SUMMARY.md for context
- **Quick navigation** - Use INDEX.md to find specific topics

206
docs/README_SCRIPTS.md Normal file
View File

@@ -0,0 +1,206 @@
# Scripts Folder - Consolidated Tool
All individual scripts have been consolidated into **`tustu_tools.py`** - a unified command-line tool with argparse interface.
## Organization
| Component | Description |
|-----------|-------------|
| **Main tool** | `tustu_tools.py` - Unified CLI with all features |
| **Documentation** | Multiple README files with complete usage information |
| **legacy/** | Original individual scripts (preserved for reference) |
| **data/** | JSON analysis and mapping files |
## Unified Tool
**Main Script:** `tustu_tools.py`
This consolidated tool provides all functionality from the following scripts:
### Merged Scripts
| Original Script | Functionality | New Command |
|----------------|---------------|-------------|
| `registration_gui.py` | PyQt6 GUI for key generation | `tustu_tools.py gui` |
| `demo_test_data_ui.py` | Demo of test data loading | Integrated into all commands |
| `test_dummy_data.py` | Test data generation | `tustu_tools.py test-data` |
| `test_email_generation.py` | Email format generation | `tustu_tools.py gen-key --email-format` |
| `fix_constructors.py` | Fix Java constructor names | `tustu_tools.py fix-constructors` |
| `fix_constructors_v2.py` | Alternative constructor fixer | Merged into fix-constructors |
| `reorganize_structure.py` | Project structure analysis | `tustu_tools.py analyze` |
| `rename_obfuscated_files.py` | Rename obfuscated Java files | Core utilities available |
### Folder Structure
```
scripts/
├── tustu_tools.py # Main unified tool
├── TUSTU_TOOLS_README.md # Complete documentation
├── README_SCRIPTS.md # This file
├── data/ # JSON data files
│ ├── README.md
│ ├── COMPLETE_RENAME_MAPPING.json
│ ├── JAVA_ANALYSIS_RESULTS.json
│ ├── PACKAGE_MAPPING.json
│ └── STRUCTURE_ANALYSIS.json
└── legacy/ # Original individual scripts
├── README.md
├── registration_gui.py
├── demo_test_data_ui.py
├── test_dummy_data.py
├── test_email_generation.py
├── fix_constructors.py
├── fix_constructors_v2.py
├── reorganize_structure.py
└── rename_obfuscated_files.py
```
## Quick Start
From the project root:
```bash
# Show all available commands
./tustu-tools --help
# Generate test data
./tustu-tools test-data -n 5
# Generate a registration key
./tustu-tools gen-key --test-data
# Fix Java constructors
./tustu-tools fix-constructors -d ./app
# Analyze project structure
./tustu-tools analyze
```
From the scripts folder:
```bash
# Show all available commands
python3 tustu_tools.py --help
# Generate test data
python3 tustu_tools.py test-data -n 5
```
## Folder Structure
```
scripts/
├── tustu_tools.py # ⭐ Main unified tool
├── TUSTU_TOOLS_README.md # Complete documentation
├── README_SCRIPTS.md # This file
├── data/ # JSON data files
│ ├── README.md
│ ├── COMPLETE_RENAME_MAPPING.json
│ ├── JAVA_ANALYSIS_RESULTS.json
│ ├── PACKAGE_MAPPING.json
│ └── STRUCTURE_ANALYSIS.json
└── legacy/ # Original individual scripts
├── README.md
├── registration_gui.py
├── demo_test_data_ui.py
├── test_dummy_data.py
├── test_email_generation.py
├── fix_constructors.py
├── fix_constructors_v2.py
├── reorganize_structure.py
└── rename_obfuscated_files.py
```
## Documentation
See **`TUSTU_TOOLS_README.md`** for complete documentation including:
- All available commands
- Detailed usage examples
- Command reference
- Migration guide from old scripts
## Legacy Scripts
The original individual scripts are preserved in this folder for reference purposes. However, **`tustu_tools.py` is now the recommended way** to access all functionality.
## Key Benefits
| Benefit | Impact |
|---------|--------|
| **Single Entry Point** | One tool instead of 8+ scripts |
| **Consistent Interface** | All commands use argparse |
| **Better Help** | `--help` for every command |
| **Easy Discovery** | Features are obvious |
| **Simple Maintenance** | One codebase to update |
| **Clean Structure** | Organized folders |
### Original Scripts Still Work
If you prefer, you can still run the original scripts directly:
```bash
python3 registration_gui.py # Launch GUI
python3 test_dummy_data.py # Generate test data
python3 fix_constructors.py # Fix constructors
```
However, we recommend using `tustu_tools.py` for all new work.
## Examples
### Before (Multiple Scripts)
```bash
python3 test_dummy_data.py
python3 test_email_generation.py
python3 fix_constructors.py
python3 reorganize_structure.py
```
### After (Unified Tool)
```bash
./tustu-tools test-data -n 5
./tustu-tools gen-key --test-data --email-format
./tustu-tools fix-constructors -d ./app
./tustu-tools analyze -o report.json
```
## Commands Overview
Run from project root with `./tustu-tools` or from scripts folder with `python3 tustu_tools.py`:
| Command | Purpose |
|---------|---------|
| `gen-key` | Generate registration keys (4/5/7/8 param algorithms) |
| `test-data` | Generate test data sets with valid keys |
| `fix-constructors` | Fix misnamed Java constructors |
| `analyze` | Analyze project structure and packages |
| `gui` | Launch PyQt6 GUI (requires PyQt6) |
**Detailed help:**
```bash
./tustu-tools <command> --help
```
## Installation
No installation needed! Just run the script:
```bash
python3 scripts/tustu_tools.py [command]
```
Or use the wrapper from project root:
```bash
./tustu-tools [command]
```
## Dependencies
Core functionality requires only Python 3 standard library.
Optional dependencies:
- **PyQt6** - Required for GUI: `pip install PyQt6`
## See Also
- `TUSTU_TOOLS_README.md` - Complete documentation
- `../README.md` - Project root documentation

86
docs/REORGANIZATION_SUMMARY.md Normal file
View File

@@ -0,0 +1,86 @@
# Scripts Reorganization Summary
**Date:** January 11, 2026
**Status:** ✅ Complete and tested
The scripts folder has been successfully reorganized for clarity and maintainability.
### What Was Done
1. **Created Unified Tool** - `tustu_tools.py`
- Merged 8 individual scripts into one
- Argparse-based CLI with subcommands
- Comprehensive help system
2. **Organized Folder Structure**
```
scripts/
├── tustu_tools.py ⭐ Main tool
├── *.md 📖 Documentation (5 files)
├── data/ 💾 JSON data files
└── legacy/ 📦 Original scripts
```
3. **Created Documentation**
- `README.md` - Quick overview and examples
- `INDEX.md` - Quick navigation guide
- `README_SCRIPTS.md` - Detailed migration info
- `TUSTU_TOOLS_README.md` - Complete tool docs
- `legacy/README.md` - Legacy scripts info
- `data/README.md` - Data files documentation
4. **Moved Files**
- 8 Python scripts → `legacy/`
- 4 JSON files → `data/`
- Clean main folder with only essentials
### Folder Details
#### Main Scripts Folder
- **1 main tool** - `tustu_tools.py` (executable)
- **5 documentation files** - Complete guides and references
#### legacy/ Subfolder
- 8 original Python scripts preserved for reference
- Still functional if needed individually
- README explains how to use them
#### data/ Subfolder
- 4 JSON analysis/mapping files
- Generated data from previous runs
- README documents each file's purpose
### Benefits Achieved
✅ **Clean organization** - Clear separation of active vs legacy code
✅ **Easy navigation** - Well-documented with multiple README files
✅ **Maintained functionality** - All features still accessible
✅ **Better discoverability** - Single tool with `--help` for everything
✅ **Preserved history** - Original scripts kept for reference
### Testing Confirmed
All commands tested and working:
- ✅ `gen-key` - Registration key generation
- ✅ `test-data` - Test data creation
- ✅ `fix-constructors` - Java constructor fixing
- ✅ `analyze` - Project analysis
- ✅ `gui` - GUI launcher (imports from legacy/)
### Usage From Project Root
```bash
./tustu-tools gen-key --test-data
./tustu-tools test-data -n 5
./tustu-tools --help
```
## Summary
The scripts folder is now clean, organized, and well-documented. All functionality is preserved and enhanced with a unified CLI interface.
### Next Steps
- Use `./tustu-tools` from project root for all operations
- Refer to `TUSTU_TOOLS_README.md` for complete documentation
- Legacy scripts remain available in `legacy/` if needed

248
docs/TEST_DATA_GENERATOR_FEATURE.md
View File

@@ -1,248 +0,0 @@
# Test Data Generator Feature
## Summary
Added automatic test data generation with "Load Test Data" buttons on all tabs. The system generates realistic dummy credentials and **valid registration keys** that pass validation.
## Changes Made
### 1. DummyDataGenerator Class
**Location**: `registration_gui.py`, lines ~18-84
**Purpose**: Generate realistic test data for quick testing
**Data Sets**:
- **First Names**: 32 common names (James, Mary, Robert, Jennifer, etc.)
- **Last Names**: 32 common surnames (Smith, Johnson, Williams, etc.)
- **Email Domains**: 10 realistic domains (gmail.com, company.com, etc.)
- **Products**: MegaLogViewer, TunerStudio, DataLogger
- **Secrets**: secret123, testkey, demo2024, abc123xyz
- **Serials**: SN001, ABC123, XYZ789, DEV001, TEST99
**Generation Logic**:
```python
data = DummyDataGenerator.generate()
# Returns: {
# 'first_name': 'John',
# 'last_name': 'Smith',
# 'email': 'john.smith@gmail.com',
# 'product': 'MegaLogViewer',
# 'secret': 'secret123',
# 'serial': 'SN001'
# }
```
### 2. Load Test Data Buttons
#### KeyGeneratorTab (All Generation Tabs)
- **Button**: Blue "Load Test Data" button
- **Position**: Left of "Generate Registration Key" button
- **Behavior**:
1. Generates random dummy data
2. Populates all input fields
3. Maps data correctly (including month='01', year='2015')
4. Shows popup with generated data details
5. Prompts user to click "Generate Registration Key"
#### EmailParserTab
- **Button**: Purple "Load Test Data" button
- **Position**: Left of "Parse Email" button
- **Behavior**:
1. Generates random dummy data
2. **Automatically generates a VALID key** using 5-param algorithm
3. Populates all output fields (name, email, serial, key)
4. Shows popup with data AND validation instructions
5. Includes product/secret in message for validation testing
### 3. Validation Guarantees
**Critical Feature**: Generated keys are mathematically valid!
The EmailParserTab's `load_test_data()` method:
```python
# Generate VALID key using actual algorithm
valid_key = RegistrationKeyGenerator.generate_key_5param(
data['first_name'],
data['last_name'],
data['product'],
data['secret'],
data['email']
)
```
This ensures:
- ✓ Keys pass exact string comparison (Java-style validation)
- ✓ Keys work with MD5 hash verification
- ✓ Keys use correct character set encoding
- ✓ Round-trip testing works (generate → parse → validate)
### 4. Java Validation Analysis
**Java Code Reviewed**:
- `bH/C0997e.java`: Key generation algorithms (4 variants)
- `com/efiAnalytics/ui/dS.java`: Registration dialog validation
**Validation Requirements Found**:
1. **Exact Match**: Keys compared with `equals()` (line 297)
2. **No Tolerance**: No fuzzy matching, must be exact
3. **Case Sensitive**: Uses exact case from MD5 hash
4. **Character Set**: Must use correct base-32 character sets
- Basic (4-param): `"123456789ABCDEFGHIJKLMNPQRSTUVWXYZ"`
- Enhanced (5/7/8-param): `"23456789ABCDEFGHJKLMNPQRSTUVWXYZ"` (no 1, I, O)
**Python Implementation Compliance**:
- ✓ Uses identical character sets
- ✓ Implements same MD5 hashing (multiple rounds)
- ✓ Matches byte manipulation logic
- ✓ Produces identical output for same inputs
### 5. Testing
Created `test_dummy_data.py` with three test suites:
#### Test 1: Data Generation
- Generates 5 random test sets
- Creates valid keys for each
- Displays all fields including keys
#### Test 2: Validation
- Tests all 4 algorithms
- Verifies keys are deterministic (same input → same output)
- Confirms consistency
#### Test 3: Email Format
- Generates complete registration email
- Shows proper format with markers
- Demonstrates round-trip capability
**All tests passing ✓**
## Usage Examples
### Scenario 1: Quick Test on Any Tab
1. Open GUI: `python3 registration_gui.py`
2. Go to any tab (e.g., "5-Parameter Standard")
3. Click blue **"Load Test Data"** button
4. See popup: "Test Data Loaded" with details
5. Click **"Generate Registration Key"**
6. Click **"Validate Key"** to verify it works
7. Result: ✓ Valid registration confirmed
### Scenario 2: Email Parser with Pre-Generated Key
1. Open GUI → **Email Parser** tab
2. Click purple **"Load Test Data"** button
3. See popup with product and secret (e.g., "Product: MegaLogViewer, Secret: secret123")
4. All fields now populated with valid data + key
5. Click **"Generate Email Format"** → formatted email created
6. Click **"Validate Key"**
7. Enter product="MegaLogViewer", secret="secret123" (from popup)
8. Result: ✓ Valid registration confirmed
### Scenario 3: Round-Trip Testing
1. **Generate Tab**: Load test data → Generate key → Copy
2. **Email Tab**: Load test data → Paste key → Generate email format
3. **Validation**: Parse email → Validate with correct product/secret
4. Result: Full workflow validated
## Technical Details
### Random Selection
```python
random.choice(DummyDataGenerator.FIRST_NAMES) # Picks one randomly
random.choice(DummyDataGenerator.PRODUCTS) # Ensures variety
```
### Email Construction
```python
email = f"{first_name.lower()}.{last_name.lower()}@{domain}"
# Example: "john.smith@gmail.com"
```
### Key Generation
```python
# EmailParserTab generates valid keys automatically
key = RegistrationKeyGenerator.generate_key_5param(
first_name, last_name, product, secret, email
)
# This key WILL pass validation with matching inputs
```
### Field Mapping
```python
field_mapping = {
'first_name': data['first_name'],
'last_name': data['last_name'],
'email': data['email'],
'product_name': data['product'],
'secret': data['secret'],
'serial': data['serial'],
'month': '01', # Fixed for 7/8-param algorithms
'year': '2015' # Fixed for 7/8-param algorithms
}
```
## Benefits
1. **Speed**: No manual data entry for testing
2. **Accuracy**: Generated keys are guaranteed valid
3. **Variety**: Random selection provides different test cases
4. **Realism**: Names, emails look authentic
5. **Consistency**: Fixed secrets/serials for reproducibility
6. **Education**: Popup messages explain next steps
7. **Validation**: Can immediately test validation workflow
## Files Modified
- `registration_gui.py`:
- Added `DummyDataGenerator` class (lines ~18-84)
- Added `load_test_data()` method to `KeyGeneratorTab` (lines ~379-413)
- Added "Load Test Data" button to `KeyGeneratorTab` (lines ~277-294)
- Added `load_test_data()` method to `EmailParserTab` (lines ~872-907)
- Added "Load Test Data" button to `EmailParserTab` (lines ~596-612)
- Added `import random` (line 9)
- Created `test_dummy_data.py`: Comprehensive test suite demonstrating functionality
## Security Note
**Test Data Only**: This is for testing/development. The fixed secrets (secret123, testkey, etc.) should never be used in production. Real implementations should use:
- Secure random secret generation
- Per-customer unique secrets
- Proper key management systems
## Java Compatibility Verification
Checked against Java source code:
**✓ Character Sets Match**:
```java
// Java (C0997e.java line 64)
"123456789ABCDEFGHIJKLMNPQRSTUVWXYZ" // Basic
"23456789ABCDEFGHJKLMNPQRSTUVWXYZ" // Enhanced
// Python (registration_gui.py lines 87-88)
CHARSET_BASIC = "123456789ABCDEFGHIJKLMNPQRSTUVWXYZ"
CHARSET_ENHANCED = "23456789ABCDEFGHJKLMNPQRSTUVWXYZ"
```
**✓ MD5 Hashing Matches**:
```java
// Java: messageDigest.update(bytes2); messageDigest.update(bytes2);
// Python: Uses identical double-update pattern
```
**✓ Validation Logic Matches**:
```java
// Java (dS.java line 297)
if (str2 != null && !str2.isEmpty() && str2.equals(strTrim4)) {
// Valid registration
}
// Python: Uses string comparison: expected_key == reg_key
```
**Result**: Generated keys will be accepted by actual Java application.