Merge pull request #5 from weslenng/fix/realign-authenticator-api-v2

fix: realign authenticator online flows with current Blizzard API

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Official Blizzard Support
+    url: https://us.battle.net/support/en/
+    about: If you are locked out of your Battle.net account, contact Blizzard. The project maintainer cannot recover your account.

.github/ISSUE_TEMPLATE/report.yml

@@ -0,0 +1,34 @@
+name: "Bug Report / API Endpoint Update"
+description: "Read before opening. Account recovery requests will be closed instantly."
+title: "[API Update]: "
+labels: ["help wanted"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        # ⚠️ STOP AND READ THIS ⚠️
+        
+        **Blizzard changed their API endpoints. This tool is currently broken.**
+        
+        * **Account Recovery:** I cannot help you. You must contact Blizzard Customer Support.
+        * **Fixing the Tool:** This tool will remain broken until a developer sniffs out and provides the updated Blizzard endpoints/payload configurations.
+
+  - type: checkboxes
+    id: acknowledgment
+    attributes:
+      label: Mandatory Acknowledgment
+      description: You must agree to these terms before submitting.
+      options:
+        - label: "I understand that this tool is currently broken due to Blizzard's API changes."
+          required: true
+        - label: "I understand that the repository maintainer CANNOT recover my Battle.net account."
+          required: true
+
+  - type: textarea
+    id: technical-details
+    attributes:
+      label: Updated Endpoint Data / Technical Contribution
+      description: "If you have intercepted the new Blizzard API traffic, please provide the new endpoints, request headers, or payload structure here."
+      placeholder: "e.g., New authentication endpoint is found at..."
+    validations:
+      required: false

README.md

@@ -1,41 +1,153 @@
 # Battle.net Authenticator Tool
 
-A Python-based tool for managing Battle.net authenticators. This tool allows you to attach new authenticators, retrieve existing device secrets, and generate TOTP keys and QR codes for easy integration with authenticator apps.
+---
 
-## Features
+# 🛑 NOT MAINTAINED / BROKEN BY BLIZZARD 🛑
 
-- Attach a new Battle.net authenticator to your account.
-- Retrieve existing device secrets using serial and restore codes.
-- Generate TOTP URLs and QR codes for use with TOTP-compatible authenticator apps.
-- Regenerate TOTP URLs and QR codes if needed.
-- Support for both US/EU accounts. - TW/CN accounts are still unknown.
+**This repository is functional ONLY as a local backup manager. Online features are dead.**
 
+### 💻 What Happened?
+Blizzard recently modified their identity API endpoints and restricted authentication scopes. This change was implemented to prevent users from extracting their raw device secrets and forcing them to use the heavy, official Battle.net mobile app for 2FA. 
+
+This tool was built using completely legal, public API access. However, because Blizzard has locked down these endpoints to restrict user choice, **you can no longer attach new authenticators or retrieve secrets online using this script.**
+
+### 🚨 Read Before Opening an Issue:
+*   **Will this be fixed?** Only if a someone manages to legally map the new endpoints or payload schemas. Pull Requests are welcome.
+*   **Are you locked out of your account?** I have zero association with Blizzard and zero access to their backend. **Do not open an issue.** You must contact [Blizzard Customer Support](https://us.battle.net/support/en/) directly to have the authenticator detached from your account. 
+*   **Spam Policy:** Any issue opened asking for a "fix," reporting an API connection failure, or asking for account help will be locked and deleted immediately.
+
+---
+
+### 🔍 Legacy Local Functions (What Still Works)
+If you already ran this tool in the past and have your `battlenet_authenticator_SERIAL.json` backup file, the tool is 100% operational offline:
+
+*   **Reconstruct TOTP:** Generates your standard RFC 6238 TOTP keys (8 digits, 30s period) and outputs a QR code to import into **Aegis, Bitwarden, 1Password, or Google Authenticator**.
+*   **Local Security:** Encrypt or decrypt your local JSON backups using strong AES-256-GCM encryption (upgraded to 600k PBKDF2 iterations in v1.3.0).
+
+---
+
+## 🛠️ Offline Usage
+
+If you are running the tool locally to regenerate keys from an existing backup:
+
+```bash
+pip install requests cryptography "qrcode[pil]"
+python bnet_auth_tool.py
+```
+
+---
+# Version History
+
+Version: 1.3.0
+
+A Python-based command-line tool for managing Battle.net software authenticators. This tool allows you to:
+
+*   Attach a new software authenticator to your Battle.net account.
+*   Retrieve the secret details of an *existing* software authenticator using its Serial Number and Restore Code.
+*   Generate standard TOTP (Time-Based One-Time Password) configuration (Base32 secret, `otpauth://` URL) and a QR code compatible with common authenticator apps (like Google Authenticator, Authy, Microsoft Authenticator, etc.).
+*   Optionally encrypt the saved authenticator details using strong AES-256-GCM encryption derived from a user-provided passphrase.
+*   Load previously saved authenticator details (plain or encrypted) to regenerate the TOTP URL and QR code.
+*   Encrypt previously saved plain-text authenticator files.
+*   Decrypt previously encrypted authenticator files (for viewing or saving as plain text).
+
+**Disclaimer:** This tool interacts with your Battle.net account and handles sensitive security information (authenticator secrets). Use it responsibly and at your own risk. Ensure you understand the security implications and securely manage any generated files and passphrases. The author is not responsible for any damage or loss resulting from the use of this tool.
+
+# Features
+
+*   **Attach New Authenticator:** Guides through attaching a new virtual authenticator.
+*   **Retrieve Existing Secret:** Recovers the secret key if you have the Serial and Restore Code.
+*   **Standard TOTP Output:** Generates Base32 secrets and `otpauth://` URLs compatible with RFC 6238 (SHA1, 8 Digits, 30s period for Battle.net).
+*   **QR Code Generation:** Creates `.png` QR codes for easy import into authenticator apps.
+*   **Secure File Encryption (Optional):** Uses AES-256-GCM with PBKDF2 (increased to 600k iterations in v1.3.0) for strong protection of saved secrets.
+*   **File Management:** Load, reconstruct, encrypt, and decrypt saved authenticator files (`.json`).
+*   **Backward Compatibility:** Can decrypt files encrypted with older versions (v1.2) that used fewer PBKDF2 iterations (100k).
+*   **Region Support:** Works with session tokens from various Battle.net regions (US, EU, KR, TW, CN detected).
+
+## Security Warning
+
+*   **Backup Your Data:** The `.json` file generated by this tool contains your authenticator's Serial, Restore Code, and the critical Device Secret. **Losing this file (especially if unencrypted) and the Restore Code means you could lose access to your authenticator.** Back up this file securely (e.g., encrypted external drive, password manager).
+*   **Protect Your Passphrase:** If you choose to encrypt the `.json` file, your passphrase is the *only* way to decrypt it. **There is no recovery for a lost passphrase.** Choose a strong, unique passphrase and store it securely.
+*   **Secure QR Codes:** The generated `.png` QR code also contains your secret key. Treat it as securely as the `.json` file. Delete it after successfully importing it into your authenticator app(s).
+*   **Session Token Exposure:** The process requires obtaining a temporary session token from your browser. Ensure you do this in a secure environment and log out afterwards if using a public computer.
+
+## Important Notice for Users Upgrading from v1.2
+
+Version `1.3.0` introduces a significant improvement to the security of *newly encrypted* files by increasing the **PBKDF2 iteration count**. This makes brute-force attacks against the encryption passphrase much harder.
+
+**Compatibility:**
+
+*   **✅ v1.3.0 CAN decrypt files encrypted by v1.2:** The new version automatically detects if a file is missing the iteration count field and assumes the old count for decryption. Your old encrypted files will work fine with v1.3.0.
+*   **❌ v1.2 CANNOT decrypt files encrypted by v1.3.0:** If you encrypt a file using v1.3.0 (either by attaching/retrieving and choosing encrypt, or using the "Encrypt existing" option), the older v1.2 script will *not* be able to decrypt it due to the mismatch in iteration counts.
+
+**Recommendation:**
+
+*   **Upgrade:** All users should upgrade to v1.3.0 or later for the improved security and compatibility handling.
+*   **(Optional) Re-encrypt:** For maximum security benefit on your existing files, you can:
+    1.  Use v1.3.0 to **decrypt** your old `.json` file (using option 5 and saving to a *new* plain file).
+    2.  Use v1.3.0 to **encrypt** that newly saved plain file (using option 4). This will re-encrypt it with the stronger 600k iterations.
+    3.  Securely delete the intermediate plain text file.
 
 ## Requirements
 
-- Python 3.7+
-- Required libraries:
-  - `cryptography` 
-  - `requests`
-  - `pillow`
-  - `qrcode`
+*   Python 3.7+
+*   Required Python libraries (install via pip):
+    *   `requests`
+    *   `cryptography`
+    *   `qrcode[pil]` (This installs both `qrcode` and the `Pillow` imaging library)
 
 ## Installation
 
-Easiest Method?
-Use the Release build.
-https://github.com/Nighthawk42/bnet_auth_tool/releases/
+**Recommended:** Download the pre-compiled executable from the [Releases page](https://github.com/Nighthawk42/bnet_auth_tool/releases/). This avoids needing Python or manual library installation.
 
-Manual Method?
+**Manual (using Python):**
 
-1. Clone the repository:
-   ```bash
-   git clone https://github.com/Nighthawk42/bnet_auth_tool.git
-   cd bnet_auth_tool
+1.  Ensure Python 3.7+ and `pip` are installed and accessible from your command line.
+2.  Clone the repository or download the source code (`.zip`).
+    ```bash
+    git clone https://github.com/Nighthawk42/bnet_auth_tool.git
+    cd bnet_auth_tool
+    ```
+3.  Install the required libraries:
+    ```bash
+    pip install -r requirements.txt
+    # Or: pip install requests cryptography "qrcode[pil]"
+    ```
 
-2. Run the script:
-   ```bash
-   pip install -r requirements.txt
-   py bnet_auth_tool.py`
+## Usage
 
-4. Follow the instructions from the console window.
+1.  Open your terminal or command prompt.
+2.  Navigate to the directory where you placed the script or executable.
+3.  Run the tool:
+    *   If using the Python script:
+        ```bash
+        python bnet_auth_tool.py
+        # or potentially: python3 bnet_auth_tool.py
+        ```
+    *   If using the executable (Windows example):
+        ```bash
+        bnet_auth_tool.exe
+        ```
+4.  The tool will display a menu with available actions:
+    *   **Attach a new authenticator:** Guides you through getting a session token and attaches a new virtual authenticator, saving the details.
+    *   **Retrieve existing device secret:** Guides you through getting a session token and uses your existing Serial/Restore code to retrieve the secret, saving the details.
+    *   **Reconstruct TOTP from JSON:** Loads a saved `.json` file (plain or encrypted, prompts for passphrase if needed) and displays the TOTP info / generates a QR code.
+    *   **Encrypt existing plain JSON file(s):** Finds unencrypted `.json` files in the directory, prompts you to select which ones to encrypt, and asks for a passphrase. *Overwrites the original file.*
+    *   **Decrypt an encrypted JSON file:** Prompts you to select an encrypted `.json` file, asks for the passphrase, and then offers to display the decrypted data or save it to a *new* plain-text `.json` file.
+    *   **Exit:** Closes the tool.
+5.  Follow the on-screen prompts for each action. Pay close attention to instructions for obtaining the session token and handling passphrases.
+
+---
+
+## Output Files
+
+*   **`.json` File:** (`battlenet_authenticator_SERIAL.json`)
+    *   Contains the Serial Number, Restore Code, raw hexadecimal Device Secret, Base32 secret, `otpauth://` URL, and a timestamp. (Encrypted files also contain salt, nonce, and iteration count).
+    *   This file is crucial for backup and recovery.
+    *   Can be saved as plain text or encrypted (recommended).
+*   **`.png` File:** (`battlenet_authenticator_SERIAL.png` or `reconstructed_SERIAL.png`)
+    *   A QR code image containing the `otpauth://` URL.
+    *   Scan this with your authenticator app to add the key.
+    *   Securely delete after successful import.
+ 
+## Donations
+[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/P5P21QRW51)