LightZirconite/Microsoft-Rewards-Script
1
0
Fork 0
mirror of https://github.com/TheNetsky/Microsoft-Rewards-Script.git synced 2026-01-20 23:13:58 +00:00
Code Issues Packages Projects Releases Wiki Activity

V2 (#365)

Browse Source 
* first commit

* Addition of a personalized activity manager and refactoring of the logic of activities

* Adding diagnostics management, including screenshot and HTML content, as well as improvements to humanize page interactions and +.

* Adding the management of newspapers and webhook settings, including filtering messages and improving the structure of the summaries sent.

* Adding a post-execution auto-date functionality, including options to update via Git and Docker, as well as a new configuration interface to manage these parameters.

* Adding accounts in Docker, with options to use an environmental file or online JSON data, as well as minimum validations for responsible accounts.

* Improving the Microsoft Rewards script display with a new headband and better log management, including colors and improved formatting for the console.

* v2

* Refactor ESLint configuration and scripts for improved TypeScript support and project structure

* Addition of the detection of suspended accounts with the gesture of the improved errors and journalization of banishment reasons

* Adding an integrated planner for programmed task execution, with configuration in Config.json and +

* Edit

* Remove texte

* Updating of documentation and adding the management of humanization in the configuration and +.

* Adding manual purchase method allowing users to spend points without automation, with monitoring of expenses and notifications.

* Correction of documentation and improvement of configuration management for manual purchase mode, adding complete documentation and appropriate banner display.

* Add comprehensive documentation for job state persistence, NTFY notifications, proxy configuration, scheduling, and auto-update features

- Introduced job state persistence documentation to track progress and resume tasks.
- Added NTFY push notifications integration guide for real-time alerts.
- Documented proxy configuration options for enhanced privacy and network management.
- Included scheduling configuration for automated script execution.
- Implemented auto-update configuration to keep installations current with Git and Docker options.

* Ajout d'Unt Système de Rapport d'Erreurs Communautaire pour Améliorerer le Débogage, incluant la Configuration et l'Envoi de Résumés D'Erreurs Anonyés à un webhook Discord.

* Mini Edit

* Mise à Jour du Readme.md pour Améliorerer la Présentation et La Claté, Ajout d'Un section sur les notifications en Temps Raine et Mise à Jour des badges pour la meille unibilité.

* Documentation update

* Edit README.md

* Edit

* Update README with legacy version link

* Improvement of location data management and webhooks, adding configurations normalization

* Force update for PR

* Improvement of documentation and configuration options for Cron integration and Docker use

* Improvement of planning documentation and adding a multi-pan-pancake in the daily execution script

* Deletion of the CommunityReport functionality in accordance with the project policy

* Addition of randomization of start -up schedules and surveillance time for planner executions

* Refactor Docker setup to use built-in scheduler, removing cron dependencies and simplifying configuration options

* Adding TOTP support for authentication, update of interfaces and configuration files to include Totp secret, and automatic generation of the Totp code when connecting.

* Fix [LOGIN-NO-PROMPT] No dialogs (xX)

* Reset the Totp field for email_1 in the accounts.example.json file

* Reset the Totp field for email_1 in the Readme.md file

* Improvement of Bing Research: Use of the 'Attacked' method for the research field, management of overlays and adding direct navigation in the event of entry failure.

* Adding a complete security policy, including directives on vulnerability management, coordinated disclosure and user security advice.

* Remove advanced environment variables section from README

* Configuration and dockerfile update: Passage to Node 22, addition of management of the purchase method, deletion of obsolete scripts

* Correction of the order of the sections in the Readme.md for better readability

* Update of Readm and Security Policy: Addition of the method of purchase and clarification of security and confidentiality practices.

* Improvement of the readability of the Readm and deletion of the mention of reporting of vulnerabilities in the security document.

* Addition of humanization management and adaptive throttling to simulate more human behavior in bot activities.

* Addition of humanization management: activation/deactivation of human gestures, configuration update and adding documentation on human mode.

* Deletion of community error report functionality to respect the privacy policy

* Addition of immediate banning alerts and vacation configuration in the Microsoft Rewards bot

* Addition of immediate banning alerts and vacation configuration in the Microsoft Rewards bot

* Added scheduling support: support for 12h and 24h formats, added options for time zone, and immediate execution on startup.

* Added window size normalization and page rendering to fit typical screens, with injected CSS styles to prevent excessive zooming.

* Added security incident management: detection of hidden recovery emails, automation blocking, and global alerts. Updated configuration files and interfaces to include recovery emails. Improved security incident documentation.

* Refactor incident alert handling: unified alert sender

* s

* Added security incident management: detect recovery email inconsistencies and send unified alerts. Implemented helper methods to manage alerts and compromised modes.

* Added heartbeat management for the scheduler: integrated a heartbeat file to report liveliness and adjusted the watchdog configuration to account for heartbeat updates.

* Edit webook

* Updated security alert management: fixed the recovery email hidden in the documentation and enabled the conclusion webhook for notifications.

* Improved security alert handling: added structured sending to webhooks for better visibility and updated callback interval in compromised mode.

* Edit conf

* Improved dependency installation: Added the --ignore-scripts option for npm ci and npm install. Updated comments in compose.yaml for clarity.

* Refactor documentation structure and enhance logging:
- Moved documentation files from 'information' to 'docs' directory for better organization.
- Added live logging configuration to support webhook logs with email redaction.
- Updated file paths in configuration and loading functions to accommodate new structure.
- Adjusted scheduler behavior to prevent immediate runs unless explicitly set.
- Improved error handling for account and config file loading.
- Enhanced security incident documentation with detailed recovery steps.

* Fix docs

* Remove outdated documentation on NTFY, Proxy, Scheduling, Security, and Auto-Update configurations; update Browser class to prioritize headless mode based on environment variable.

* Addition of documentation for account management and Totp, Docker Guide, and Update of the Documentation Index.

* Updating Docker documentation: simplification of instructions and adding links to detailed guides. Revision of configuration options and troubleshooting sections.

* Edit

* Edit docs

* Enhance documentation for Scheduler, Security, and Auto-Update features

- Revamped the Scheduler documentation to include detailed features, configuration options, and usage examples.
- Expanded the Security guide with comprehensive incident response strategies, privacy measures, and monitoring practices.
- Updated the Auto-Update section to clarify configuration, methods, and best practices for maintaining system integrity.

* Improved error handling and added crash recovery in the Microsoft Rewards bot. Added configuration for automatic restart and handling of local search queries when trends fail.

* Fixed initial point counting in MicrosoftRewardsBot and improved error handling when sending summaries to webhooks.

* Added unified support for notifications and improved handling of webhook configurations in the normalizeConfig and log functions.

* UPDATE LOGIN

* EDIT LOGIN

* Improved login error handling: added recovery mismatch detection and the ability to switch to password authentication.

* Added a full reference to configuration in the documentation and improved log and error handling in the code.

* Added context management for conclusion webhooks and improved user configuration for notifications.

* Mini edit

* Improved logic for extracting masked emails for more accurate matching during account recovery.
This commit is contained in:
Light
2025-09-26 18:58:33 +02:00
committed by GitHub
parent 02160a07d9
commit 15f62963f8
60 changed files with 8186 additions and 1355 deletions
Download Patch File Download Diff File Expand all files Collapse all files

94
docs/accounts.md Normal file
View File

@@ -0,0 +1,94 @@
# 👤 Accounts & TOTP (2FA)
<div align="center">
**🔐 Secure Microsoft account setup with 2FA support**
*Everything you need to configure authentication*
</div>
---
## 📍 File Location & Options
The bot needs Microsoft account credentials to log in and complete activities. Here's how to provide them:
### **Default Location**
```
src/accounts.json
```
### **Environment Overrides** (Docker/CI)
- **`ACCOUNTS_FILE`** — Path to accounts file (e.g., `/data/accounts.json`)
- **`ACCOUNTS_JSON`** — Inline JSON string (useful for CI/CD)
The loader tries: `ACCOUNTS_JSON` → `ACCOUNTS_FILE` → default locations in project root.
## Schema
Each account has at least `email` and `password`.
```
{
"accounts": [
{
"email": "email_1",
"password": "password_1",
"totp": "",
"recoveryEmail": "your_email@domain.com",
"proxy": {
"proxyAxios": true,
"url": "",
"port": 0,
"username": "",
"password": ""
}
}
]
}
```
- `totp` (optional): Base32 secret for Time‑based One‑Time Passwords (2FA). If set, the bot generates the 6‑digit code automatically when asked by Microsoft.
- `recoveryEmail` (optional): used to validate masked recovery prompts.
- `proxy` (optional): per‑account proxy config. See the [Proxy guide](./proxy.md).
## How to get your TOTP secret
1) In your Microsoft account security settings, add an authenticator app.
2) When shown the QR code, choose the option to enter the code manually — this reveals the Base32 secret.
3) Copy that secret (only the text after `secret=` if you have an otpauth URL) into the `totp` field.
Security tips:
- Never commit real secrets to Git.
- Prefer `ACCOUNTS_FILE` or `ACCOUNTS_JSON` in production.
## Examples
- Single account, no 2FA:
```
{"accounts":[{"email":"a@b.com","password":"pass","totp":"","recoveryEmail":"","proxy":{"proxyAxios":true,"url":"","port":0,"username":"","password":""}}]}
```
- Single account with TOTP secret:
```
{"accounts":[{"email":"a@b.com","password":"pass","totp":"JBSWY3DPEHPK3PXP","recoveryEmail":"","proxy":{"proxyAxios":true,"url":"","port":0,"username":"","password":""}}]}
```
- Multiple accounts:
```
{"accounts":[
{"email":"a@b.com","password":"pass","totp":"","recoveryEmail":"" ,"proxy":{"proxyAxios":true,"url":"","port":0,"username":"","password":""}},
{"email":"c@d.com","password":"pass","totp":"","recoveryEmail":"" ,"proxy":{"proxyAxios":true,"url":"","port":0,"username":"","password":""}}
]}
```
## Troubleshooting
- “accounts file not found”: ensure the file exists, or set `ACCOUNTS_FILE` to the correct path.
- 2FA prompt not filled: verify `totp` is a valid Base32 secret; time on the host/container should be correct.
- Locked account: the bot will log and skip; resolve manually then re‑enable.
---
## 🔗 Related Guides
- **[Getting Started](./getting-started.md)** — Initial setup and configuration
- **[Docker](./docker.md)** — Container deployment with accounts
- **[Security](./security.md)** — Account protection and incident response
- **[NTFY Notifications](./ntfy.md)** — Get alerts for login issues

206
docs/buy-mode.md Normal file
View File

@@ -0,0 +1,206 @@
# 💳 Buy Mode
<div align="center">
**🛒 Manual redemption with live point monitoring**
*Track your spending while maintaining full control*
</div>
---
## 🎯 What is Buy Mode?
Buy Mode allows you to **manually redeem rewards** while the script **passively monitors** your point balance. Perfect for safe redemptions without automation interference.
### **Key Features**
- 👀 **Passive monitoring** — No clicks or automation
- 🔄 **Real-time tracking** — Instant spending alerts
- 📱 **Live notifications** — Discord/NTFY integration
- ⏱️ **Configurable duration** — Set your own time limit
- 📊 **Session summary** — Complete spending report
---
## 🚀 How to Use
### **Command Options**
```bash
# Monitor specific account
npm start -- -buy your@email.com
# Monitor first account in accounts.json
npm start -- -buy
# Alternative: Enable in config (see below)
```
### **What Happens Next**
1. **🖥️ Dual Tab System Opens**
- **Monitor Tab** — Background monitoring (auto-refresh)
- **User Tab** — Your control for redemptions/browsing
2. **📊 Passive Point Tracking**
- Reads balance every ~10 seconds
- Detects spending when points decrease
- Zero interference with your browsing
3. **🔔 Real-time Alerts**
- Instant notifications when spending detected
- Shows amount spent + current balance
- Tracks cumulative session spending
---
## ⚙️ Configuration
### **Set Duration in Config**
Add to `src/config.json`:
```json
{
"buyMode": {
"enabled": false,
"maxMinutes": 45
}
}
```
| Setting | Default | Description |
|---------|---------|-------------|
| `enabled` | `false` | Force buy mode without CLI flag |
| `maxMinutes` | `45` | Auto-stop after N minutes |
### **Enable Notifications**
Buy mode works with existing notification settings:
```json
{
"conclusionWebhook": {
"enabled": true,
"url": "https://discord.com/api/webhooks/YOUR_URL"
},
"ntfy": {
"enabled": true,
"url": "https://ntfy.sh",
"topic": "rewards"
}
}
```
---
## 🖥️ Terminal Output
### **Startup**
```
███╗ ███╗███████╗ ██████╗ ██╗ ██╗██╗ ██╗
████╗ ████║██╔════╝ ██╔══██╗██║ ██║╚██╗ ██╔╝
██╔████╔██║███████╗ ██████╔╝██║ ██║ ╚████╔╝
██║╚██╔╝██║╚════██║ ██╔══██╗██║ ██║ ╚██╔╝
██║ ╚═╝ ██║███████║ ██████╔╝╚██████╔╝ ██║
╚═╝ ╚═╝╚══════╝ ╚═════╝ ╚═════╝ ╚═╝
Manual Purchase Mode • Passive Monitoring
[BUY-MODE] Opening dual-tab system for safe redemptions...
[BUY-MODE] Monitor tab: Background point tracking
[BUY-MODE] User tab: Your control for purchases/browsing
```
### **Live Monitoring**
```
[BUY-MODE] Current balance: 15,000 points
[BUY-MODE] 🛒 Spending detected: -500 points (new balance: 14,500)
[BUY-MODE] Session total spent: 500 points
```
---
## 📋 Use Cases
| Scenario | Benefit |
|----------|---------|
| **🎁 Gift Card Redemption** | Track exact point cost while redeeming safely |
| **🛍️ Microsoft Store Purchases** | Monitor spending across multiple items |
| **✅ Account Verification** | Ensure point changes match expected activity |
| **📊 Spending Analysis** | Real-time tracking of reward usage patterns |
| **🔒 Safe Browsing** | Use Microsoft Rewards normally with monitoring |
---
## 🛠️ Troubleshooting
| Problem | Solution |
|---------|----------|
| **Monitor tab closes** | Script auto-reopens in background |
| **No spending alerts** | Check webhook/NTFY config; verify notifications enabled |
| **Session too short** | Increase `maxMinutes` in config |
| **Login failures** | Verify account credentials in `accounts.json` |
| **Points not updating** | Check internet connection; try refresh |
---
## 🔗 Related Guides
- **[Getting Started](./getting-started.md)** — Initial setup and configuration
- **[Accounts & 2FA](./accounts.md)** — Microsoft account setup
- **[NTFY Notifications](./ntfy.md)** — Mobile push alerts
- **[Discord Webhooks](./conclusionwebhook.md)** — Server notifications
## Terminal Output
When you start buy mode, you'll see:
```
███╗ ███╗███████╗ ██████╗ ██╗ ██╗██╗ ██╗
████╗ ████║██╔════╝ ██╔══██╗██║ ██║╚██╗ ██╔╝
██╔████╔██║███████╗ ██████╔╝██║ ██║ ╚████╔╝
██║╚██╔╝██║╚════██║ ██╔══██╗██║ ██║ ╚██╔╝
██║ ╚═╝ ██║███████║ ██████╔╝╚██████╔╝ ██║
╚═╝ ╚═╝╚══════╝ ╚═════╝ ╚═════╝ ╚═╝
Manual Purchase Mode • Passive Monitoring
[BUY-MODE] Buy mode ENABLED for your@email.com. We'll open 2 tabs:
(1) monitor tab (auto-refreshes), (2) your browsing tab
[BUY-MODE] The monitor tab may refresh every ~10s. Use the other tab...
[BUY-MODE] Opened MONITOR tab (auto-refreshes to track points)
[BUY-MODE] Opened USER tab (use this one to redeem/purchase freely)
[BUY-MODE] Logged in as your@email.com. Buy mode is active...
```
During monitoring:
```
[BUY-MODE] Detected spend: -500 points (current: 12,500)
[BUY-MODE] Monitor tab was closed; reopening in background...
```
## Features
- ✅ **Non-intrusive**: No clicks or navigation in your browsing tab
- ✅ **Real-time alerts**: Instant notifications when points are spent
- ✅ **Auto-recovery**: Reopens monitor tab if accidentally closed
- ✅ **Webhook support**: Works with Discord and NTFY notifications
- ✅ **Configurable duration**: Set your own monitoring time limit
- ✅ **Session tracking**: Complete summary of spending activity
## Use Cases
- **Manual redemptions**: Redeem gift cards or rewards while tracking spending
- **Account verification**: Monitor point changes during manual account activities
- **Spending analysis**: Track how points are being used in real-time
- **Safe browsing**: Use Microsoft Rewards normally while monitoring balance
## Notes
- Monitor tab runs in background and may refresh periodically
- Your main browsing tab is completely under your control
- Session data is saved automatically for future script runs
- Buy mode works with existing notification configurations
- No automation or point collection occurs in this mode
## Troubleshooting
- **Monitor tab closed**: Script automatically reopens it in background
- **No notifications**: Check webhook/NTFY configuration in `config.json`
- **Session timeout**: Increase `maxMinutes` if you need longer monitoring
- **Login issues**: Ensure account credentials are correct in `accounts.json`

389
docs/conclusionwebhook.md Normal file
View File

@@ -0,0 +1,389 @@
# 📊 Discord Conclusion Webhook
<div align="center">
**🎯 Comprehensive session summaries via Discord**
*Complete execution reports delivered instantly*
</div>
---
## 🎯 What is the Conclusion Webhook?
The conclusion webhook sends a **detailed summary notification** at the end of each script execution via Discord, providing a complete overview of the session's results across all accounts.
### **Key Features**
- 📊 **Session overview** — Total accounts processed, success/failure counts
- 💎 **Points summary** — Starting points, earned points, final totals
- ⏱️ **Performance metrics** — Execution times, efficiency statistics
- ❌ **Error reporting** — Issues encountered during execution
- 💳 **Buy mode detection** — Point spending alerts and tracking
- 🎨 **Rich embeds** — Color-coded, well-formatted Discord messages
---
## ⚙️ Configuration
### **Basic Setup**
```json
{
"notifications": {
"conclusionWebhook": {
"enabled": true,
"url": "https://discord.com/api/webhooks/123456789/abcdef-webhook-token-here"
}
}
}
```
### **Configuration Options**
| Setting | Description | Example |
|---------|-------------|---------|
| `enabled` | Enable conclusion webhook | `true` |
| `url` | Discord webhook URL | Full webhook URL from Discord |
---
## 🚀 Discord Setup
### **Step 1: Create Webhook**
1. **Open Discord** and go to your server
2. **Right-click** on the channel for notifications
3. **Select "Edit Channel"**
4. **Go to "Integrations" tab**
5. **Click "Create Webhook"**
### **Step 2: Configure Webhook**
- **Name** — "MS Rewards Summary"
- **Avatar** — Upload rewards icon (optional)
- **Channel** — Select appropriate channel
- **Copy webhook URL**
### **Step 3: Add to Config**
```json
{
"notifications": {
"conclusionWebhook": {
"enabled": true,
"url": "YOUR_COPIED_WEBHOOK_URL_HERE"
}
}
}
```
---
## 📋 Message Format
### **Rich Embed Summary**
#### **Header Section**
```
🎯 Microsoft Rewards Summary
⏰ Completed at 2025-01-20 14:30:15
📈 Total Runtime: 25m 36s
```
#### **Account Statistics**
```
📊 Accounts: 3 • 0 with issues
```
#### **Points Overview**
```
💎 Points: 15,230 → 16,890 (+1,660)
```
#### **Performance Metrics**
```
⏱️ Average Duration: 8m 32s
📈 Cumulative Runtime: 25m 36s
```
#### **Buy Mode Detection** (if applicable)
```
💳 Buy Mode Activity Detected
Total Spent: 1,200 points across 2 accounts
```
### **Account Breakdown**
#### **Successful Account**
```
👤 user@example.com
Points: 5,420 → 6,140 (+720)
Duration: 7m 23s
Status: ✅ Completed successfully
```
#### **Failed Account**
```
👤 problem@example.com
Points: 3,210 → 3,210 (+0)
Duration: 2m 15s
Status: ❌ Failed - Login timeout
```
#### **Buy Mode Account**
```
💳 spender@example.com
Session Spent: 500 points
Available: 12,500 points
Status: 💳 Purchase activity detected
```
---
## 📊 Message Examples
### **Successful Session**
```discord
🎯 Microsoft Rewards Summary
📊 Accounts: 3 • 0 with issues
💎 Points: 15,230 → 16,890 (+1,660)
⏱️ Average Duration: 8m 32s
📈 Cumulative Runtime: 25m 36s
👤 user1@example.com
Points: 5,420 → 6,140 (+720)
Duration: 7m 23s
Status: ✅ Completed successfully
👤 user2@example.com
Points: 4,810 → 5,750 (+940)
Duration: 9m 41s
Status: ✅ Completed successfully
👤 user3@example.com
Points: 5,000 → 5,000 (+0)
Duration: 8m 32s
Status: ✅ Completed successfully
```
### **Session with Issues**
```discord
🎯 Microsoft Rewards Summary
📊 Accounts: 3 • 1 with issues
💎 Points: 15,230 → 15,950 (+720)
⏱️ Average Duration: 6m 15s
📈 Cumulative Runtime: 18m 45s
👤 user1@example.com
Points: 5,420 → 6,140 (+720)
Duration: 7m 23s
Status: ✅ Completed successfully
👤 user2@example.com
Points: 4,810 → 4,810 (+0)
Duration: 2m 15s
Status: ❌ Failed - Login timeout
👤 user3@example.com
Points: 5,000 → 5,000 (+0)
Duration: 9m 07s
Status: ⚠️ Partially completed - Quiz failed
```
### **Buy Mode Detection**
```discord
🎯 Microsoft Rewards Summary
📊 Accounts: 2 • 0 with issues
💎 Points: 25,500 → 24,220 (-1,280)
💳 Buy Mode Activity Detected
Total Spent: 1,500 points across 1 account
👤 buyer@example.com
Points: 15,000 → 13,500 (-1,500)
Duration: 12m 34s
Status: 💳 Buy mode detected
Activities: Purchase completed, searches skipped
👤 normal@example.com
Points: 10,500 → 10,720 (+220)
Duration: 8m 45s
Status: ✅ Completed successfully
```
---
## 🤝 Integration with Other Notifications
### **Webhook vs Conclusion Webhook**
| Feature | Real-time Webhook | Conclusion Webhook |
|---------|------------------|-------------------|
| **Timing** | During execution | End of session only |
| **Content** | Errors, warnings, progress | Comprehensive summary |
| **Frequency** | Multiple per session | One per session |
| **Purpose** | Immediate alerts | Session overview |
### **Recommended Combined Setup**
```json
{
"notifications": {
"webhook": {
"enabled": true,
"url": "https://discord.com/api/webhooks/.../real-time"
},
"conclusionWebhook": {
"enabled": true,
"url": "https://discord.com/api/webhooks/.../summary"
},
"ntfy": {
"enabled": true,
"url": "https://ntfy.sh",
"topic": "rewards-mobile"
}
}
}
```
### **Benefits of Combined Setup**
- ⚡ **Real-time webhook** — Immediate error alerts
- 📊 **Conclusion webhook** — Comprehensive session summary
- 📱 **NTFY** — Mobile notifications for critical issues
---
## 🎛️ Advanced Configuration
### **Multiple Webhooks**
```json
{
"notifications": {
"webhook": {
"enabled": true,
"url": "https://discord.com/api/webhooks/.../errors-channel"
},
"conclusionWebhook": {
"enabled": true,
"url": "https://discord.com/api/webhooks/.../summary-channel"
}
}
}
```
### **Channel Organization**
#### **Recommended Discord Structure**
- **#rewards-errors** — Real-time error notifications (webhook)
- **#rewards-summary** — End-of-run summaries (conclusionWebhook)
- **#rewards-logs** — Detailed text logs (manual uploads)
#### **Channel Settings**
- **Notification settings** — Configure per your preference
- **Webhook permissions** — Limit to specific channels
- **Message history** — Enable for tracking trends
---
## 🔒 Security & Privacy
### **Webhook Security Best Practices**
- 🔐 Use **dedicated Discord server** for notifications
- 🎯 **Limit permissions** to specific channels only
- 🔄 **Regenerate URLs** if compromised
- 🚫 **Don't share** webhook URLs publicly
### **Data Transmission**
- ✅ **Summary statistics** only
- ✅ **Points and email** addresses
- ❌ **No passwords** or sensitive tokens
- ❌ **No personal information** beyond emails
### **Data Retention**
- 💾 **Discord stores** messages per server settings
- 🗑️ **No local storage** by the script
- ✂️ **Manual deletion** possible anytime
- 📝 **Webhook logs** may be retained by Discord
---
## 🧪 Testing & Debugging
### **Manual Webhook Test**
```bash
curl -X POST \
-H "Content-Type: application/json" \
-d '{"content":"Test message from rewards script"}' \
"YOUR_WEBHOOK_URL_HERE"
```
### **Script Debug Mode**
```powershell
$env:DEBUG_REWARDS_VERBOSE=1; npm start
```
### **Success Indicators**
```
[INFO] Sending conclusion webhook...
[INFO] Conclusion webhook sent successfully
```
### **Error Messages**
```
[ERROR] Failed to send conclusion webhook: Invalid webhook URL
```
---
## 🛠️ Troubleshooting
| Problem | Solution |
|---------|----------|
| **No summary received** | Check webhook URL; verify Discord permissions |
| **Malformed messages** | Validate webhook URL; check Discord server status |
| **Missing information** | Ensure script completed; check for execution errors |
| **Rate limited** | Single webhook per session prevents this |
### **Common Fixes**
- ✅ **Webhook URL** — Must be complete Discord webhook URL
- ✅ **Channel permissions** — Webhook must have send permissions
- ✅ **Server availability** — Discord server must be accessible
- ✅ **Script completion** — Summary only sent after full execution
---
## ⚡ Performance Impact
### **Resource Usage**
- 📨 **Single HTTP request** at script end
- ⚡ **Non-blocking operation** — No execution delays
- 💾 **Payload size** — Typically < 2KB
- 🌐 **Delivery time** — Usually < 1 second
### **Benefits**
- ✅ **No impact** on account processing
- ✅ **Minimal memory** footprint
- ✅ **No disk storage** required
- ✅ **Negligible bandwidth** usage
---
## 🎨 Customization
### **Embed Features**
- 🎨 **Color-coded** status indicators
- 🎭 **Emoji icons** for visual clarity
- 📊 **Structured fields** for easy reading
- ⏰ **Timestamps** and duration info
### **Discord Integration**
- 💬 **Thread notifications** support
- 👥 **Role mentions** (configure in webhook)
- 🔍 **Searchable messages** for history
- 📂 **Archive functionality** for records
---
## 🔗 Related Guides
- **[NTFY Notifications](./ntfy.md)** — Mobile push notifications
- **[Getting Started](./getting-started.md)** — Initial setup and configuration
- **[Buy Mode](./buy-mode.md)** — Manual purchasing with monitoring
- **[Security](./security.md)** — Privacy and data protection

227
docs/config.md Normal file
View File

@@ -0,0 +1,227 @@
# ⚙️ Configuration Guide
This page documents every field in `config.json`. You can keep the file lean by deleting blocks you do not use – missing values fall back to defaults. Comments (`// ...`) are supported in the JSON thanks to a custom parser.
> NOTE: Previous versions had `logging.live` (live streaming webhook); it was removed and replaced by a simple `logging.redactEmails` flag.
---
## Top-Level Fields
### baseURL
Internal Microsoft Rewards base. Leave it unless you know what you are doing.
### sessionPath
Directory where session data (cookies / fingerprints / job-state) is stored.
---
## browser
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| headless | boolean | false | Run browser UI-less. Setting to `false` can improve stability or help visual debugging. |
| globalTimeout | string/number | "30s" | Max time for common Playwright operations. Accepts ms number or time string (e.g. `"45s"`, `"2min"`). |
---
## execution
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| parallel | boolean | false | Run desktop + mobile simultaneously (higher resource usage). |
| runOnZeroPoints | boolean | false | Skip full run early if there are zero points available (saves time). |
| clusters | number | 1 | Number of process clusters (multi-process concurrency). |
| passesPerRun | number | 1 | Advanced: extra full passes per started run. |
---
## buyMode
Manual redeem / purchase assistance.
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| enabled (CLI `-buy`) | boolean | false | Enable buy mode (usually via CLI argument). |
| maxMinutes | number | 45 | Max session length for buy mode. |
---
## fingerprinting.saveFingerprint
Persist browser fingerprints per device type for consistency.
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| mobile | boolean | false | Save/reuse a consistent mobile fingerprint. |
| desktop | boolean | false | Save/reuse a consistent desktop fingerprint. |
---
## search
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| useLocalQueries | boolean | false | Use locale-specific query sources instead of global ones. |
### search.settings
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| useGeoLocaleQueries | boolean | false | Blend geo / locale into chosen queries. |
| scrollRandomResults | boolean | true | Random scroll during search pages to look natural. |
| clickRandomResults | boolean | true | Occasionally click safe results. |
| retryMobileSearchAmount | number | 2 | Retries if mobile searches didn’t yield points. |
| delay.min / delay.max | string/number | 3–5min | Delay between searches (ms or time string). |
---
## humanization
Human‑like behavior simulation.
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| enabled | boolean | true | Global on/off. |
| stopOnBan | boolean | true | Stop processing further accounts if a ban is detected. |
| immediateBanAlert | boolean | true | Fire notification immediately upon ban detection. |
| actionDelay.min/max | number/string | 150–450ms | Random micro-delay per action. |
| gestureMoveProb | number | 0.4 | Probability of a small mouse move gesture. |
| gestureScrollProb | number | 0.2 | Probability of a small scroll gesture. |
| allowedWindows | string[] | [] | Local time windows (e.g. `["08:30-11:00","19:00-22:00"]`). Outside windows, run waits. |
---
## vacation
Random contiguous block of days off per month.
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| enabled | boolean | false | Activate monthly break behavior. |
| minDays | number | 3 | Minimum skipped days per month. |
| maxDays | number | 5 | Maximum skipped days per month. |
---
## retryPolicy
Generic transient retry/backoff.
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| maxAttempts | number | 3 | Max tries for retryable blocks. |
| baseDelay | number | 1000 | Initial delay in ms. |
| maxDelay | number/string | 30s | Max backoff delay. |
| multiplier | number | 2 | Exponential backoff multiplier. |
| jitter | number | 0.2 | Randomization factor (0..1). |
---
## workers
Enable/disable scripted task categories.
| Key | Default | Description |
|-----|---------|-------------|
| doDailySet | true | Daily set activities. |
| doMorePromotions | true | Promotional tasks. |
| doPunchCards | true | Punch card flows. |
| doDesktopSearch | true | Desktop searches. |
| doMobileSearch | true | Mobile searches. |
| doDailyCheckIn | true | Daily check-in. |
| doReadToEarn | true | Reading tasks. |
| bundleDailySetWithSearch | false | Immediately start desktop search bundle after daily set. |
---
## proxy
| Key | Default | Description |
|-----|---------|-------------|
| proxyGoogleTrends | true | Route Google Trends fetch through proxy if set. |
| proxyBingTerms | true | Route Bing query source fetch through proxy if set. |
---
## notifications
Manages notification channels (Discord webhooks, NTFY, etc.).
### notifications.webhook
Primary webhook (can be used for summary or generic messages).
| Key | Default | Description |
|-----|---------|-------------|
| enabled | false | Allow sending webhook-based notifications. |
| url | "" | Webhook endpoint. |
### notifications.conclusionWebhook
Rich end-of-run summary (if enabled separately).
| Key | Default | Description |
|-----|---------|-------------|
| enabled | false | Enable run summary posting. |
| url | "" | Webhook endpoint. |
### notifications.ntfy
Lightweight push notifications.
| Key | Default | Description |
|-----|---------|-------------|
| enabled | false | Enable NTFY push. |
| url | "" | Base NTFY server URL (e.g. https://ntfy.sh). |
| topic | rewards | Topic/channel name. |
| authToken | "" | Bearer token if your server requires auth. |
---
## logging
| Key | Type | Description |
|-----|------|-------------|
| excludeFunc | string[] | Log buckets suppressed in console + any webhook usage. |
| webhookExcludeFunc | string[] | Buckets suppressed specifically for webhook output. |
| redactEmails | boolean | If true, email addresses are partially masked in logs. |
_Removed fields_: `live.enabled`, `live.url`, `live.redactEmails` — replaced by `redactEmails` only.
---
## diagnostics
Capture evidence when something fails.
| Key | Default | Description |
|-----|---------|-------------|
| enabled | true | Master switch for diagnostics. |
| saveScreenshot | true | Save screenshot on failure. |
| saveHtml | true | Save HTML snapshot on failure. |
| maxPerRun | 2 | Cap artifacts per run per failure type. |
| retentionDays | 7 | Old run artifacts pruned after this many days. |
---
## jobState
Checkpoint system to avoid duplicate work.
| Key | Default | Description |
|-----|---------|-------------|
| enabled | true | Enable job state tracking. |
| dir | "" | Custom directory (default: `<sessionPath>/job-state`). |
---
## schedule
Built-in scheduler (avoids external cron inside container or host).
| Key | Default | Description |
|-----|---------|-------------|
| enabled | false | Enable scheduling loop. |
| useAmPm | false | If true, parse `time12`; else use `time24`. |
| time12 | 9:00 AM | 12‑hour format time (only if useAmPm=true). |
| time24 | 09:00 | 24‑hour format time (only if useAmPm=false). |
| timeZone | America/New_York | IANA zone string (e.g. Europe/Paris). |
| runImmediatelyOnStart | false | Run one pass instantly in addition to daily schedule. |
_Legacy_: If both `time12` and `time24` are empty, a legacy `time` (HH:mm) may still be read.
---
## update
Auto-update behavior after a run.
| Key | Default | Description |
|-----|---------|-------------|
| git | true | Pull latest git changes after run. |
| docker | false | Recreate container (if running in Docker orchestration). |
| scriptPath | setup/update/update.mjs | Custom script executed for update flow. |
---
## Security / Best Practices
- Keep `redactEmails` true if you share logs publicly.
- Use a private NTFY instance or secure Discord webhooks (do not leak URLs).
- Avoid setting `headless` false on untrusted remote servers.
---
## Minimal Example
```jsonc
{
"browser": { "headless": true },
"execution": { "parallel": false },
"workers": { "doDailySet": true, "doDesktopSearch": true, "doMobileSearch": true },
"logging": { "redactEmails": true }
}
```
## Common Tweaks
| Goal | Change |
|------|--------|
| Faster dev feedback | Set `browser.headless` to false and shorten search delays. |
| Reduce detection risk | Keep humanization enabled, add vacation window. |
| Silent mode | Add more buckets to `excludeFunc`. |
| Skip mobile searches | Set `workers.doMobileSearch=false`. |
| Use daily schedule | Set `schedule.enabled=true` and adjust `time24` + `timeZone`. |
---
## Changelog Notes
- Removed live webhook streaming complexity; now simpler logging.
- Centralized redaction logic under `logging.redactEmails`.
If something feels undocumented or unclear, open a documentation issue or extend this page.

225
docs/diagnostics.md Normal file
View File

@@ -0,0 +1,225 @@
# 🔍 Diagnostics & Error Capture
<div align="center">
**🛠️ Automatic error screenshots and HTML snapshots**
*Debug smarter with visual evidence*
</div>
---
## 🎯 What is Diagnostics?
The diagnostics system **automatically captures** error screenshots and HTML snapshots when issues occur during script execution, providing visual evidence for troubleshooting.
### **Key Features**
- 📸 **Auto-screenshot** — Visual error capture
- 📄 **HTML snapshots** — Complete page source
- 🚦 **Rate limiting** — Prevents storage bloat
- 🗂️ **Auto-cleanup** — Configurable retention
- 🔒 **Privacy-safe** — Local storage only
---
## ⚙️ Configuration
### **Basic Setup**
Add to `src/config.json`:
```json
{
"diagnostics": {
"enabled": true,
"saveScreenshot": true,
"saveHtml": true,
"maxPerRun": 2,
"retentionDays": 7
}
}
```
### **Configuration Options**
| Setting | Default | Description |
|---------|---------|-------------|
| `enabled` | `true` | Master toggle for diagnostics capture |
| `saveScreenshot` | `true` | Capture PNG screenshots on errors |
| `saveHtml` | `true` | Save page HTML content on errors |
| `maxPerRun` | `2` | Maximum captures per script run |
| `retentionDays` | `7` | Auto-delete reports older than N days |
---
## 🚀 How It Works
### **Automatic Triggers**
The system captures when these errors occur:
- ⏱️ **Page navigation timeouts**
- 🎯 **Element selector failures**
- 🔐 **Authentication errors**
- 🌐 **Network request failures**
- ⚡ **JavaScript execution errors**
### **Capture Process**
1. **Error Detection** — Script encounters unhandled error
2. **Visual Capture** — Screenshot + HTML snapshot
3. **Safe Storage** — Local `reports/` folder
4. **Continue Execution** — No blocking or interruption
---
## 📁 File Structure
### **Storage Organization**
```
reports/
├── 2025-01-20/
│ ├── error_abc123_001.png
│ ├── error_abc123_001.html
│ ├── error_def456_002.png
│ └── error_def456_002.html
└── 2025-01-21/
└── ...
```
### **File Naming Convention**
```
error_[runId]_[sequence].[ext]
```
- **RunId** — Unique identifier for each script execution
- **Sequence** — Incremental counter (001, 002, etc.)
- **Extension** — `.png` for screenshots, `.html` for source
---
## 🧹 Retention Management
### **Automatic Cleanup**
- Runs after each script completion
- Deletes entire date folders older than `retentionDays`
- Prevents unlimited disk usage growth
### **Manual Cleanup**
```powershell
# Remove all diagnostic reports
Remove-Item -Recurse -Force reports/
# Remove reports older than 3 days
Get-ChildItem reports/ | Where-Object {$_.LastWriteTime -lt (Get-Date).AddDays(-3)} | Remove-Item -Recurse -Force
```
---
## 📊 Use Cases
| Scenario | Benefit |
|----------|---------|
| **🐛 Development & Debugging** | Visual confirmation of page state during errors |
| **🔍 Element Detection Issues** | HTML source analysis for selector problems |
| **📈 Production Monitoring** | Evidence collection for account issues |
| **⚡ Performance Analysis** | Timeline reconstruction of automation failures |
---
## ⚡ Performance Impact
### **Resource Usage**
- **Screenshots** — ~100-500KB each
- **HTML files** — ~50-200KB each
- **CPU overhead** — Minimal (only during errors)
- **Memory impact** — Asynchronous, non-blocking
### **Storage Optimization**
- Daily cleanup prevents accumulation
- Rate limiting via `maxPerRun`
- Configurable retention period
---
## 🎛️ Environment Settings
### **Development Mode**
```json
{
"diagnostics": {
"enabled": true,
"maxPerRun": 5,
"retentionDays": 14
}
}
```
### **Production Mode**
```json
{
"diagnostics": {
"enabled": true,
"maxPerRun": 2,
"retentionDays": 3
}
}
```
### **Debug Verbose Logging**
```powershell
$env:DEBUG_REWARDS_VERBOSE=1; npm start
```
---
## 🛠️ Troubleshooting
| Problem | Solution |
|---------|----------|
| **No captures despite errors** | Check `enabled: true`; verify `reports/` write permissions |
| **Excessive storage usage** | Reduce `maxPerRun`; decrease `retentionDays` |
| **Missing screenshots** | Verify browser screenshot API; check memory availability |
| **Cleanup not working** | Ensure script completes successfully for auto-cleanup |
### **Common Capture Locations**
- **Login issues** — Authentication page screenshots
- **Activity failures** — Element detection errors
- **Network problems** — Timeout and connection errors
- **Navigation issues** — Page load failures
---
## 🔗 Integration
### **With Notifications**
Diagnostics complement [Discord Webhooks](./conclusionwebhook.md) and [NTFY](./ntfy.md):
- **Webhooks** — Immediate error alerts
- **Diagnostics** — Visual evidence for investigation
- **Combined** — Complete error visibility
### **With Development Workflow**
```bash
# 1. Run script with diagnostics
npm start
# 2. Check for captures after errors
ls reports/$(date +%Y-%m-%d)/
# 3. Analyze screenshots and HTML
# Open .png files for visual state
# Review .html files for DOM structure
```
---
## 🔒 Privacy & Security
- **Local Only** — All captures stored locally
- **No Uploads** — Zero external data transmission
- **Account Info** — May contain sensitive data
- **Secure Storage** — Use appropriate folder permissions
- **Regular Cleanup** — Recommended for sensitive environments
---
## 🔗 Related Guides
- **[Getting Started](./getting-started.md)** — Initial setup and configuration
- **[Discord Webhooks](./conclusionwebhook.md)** — Error notification alerts
- **[NTFY Notifications](./ntfy.md)** — Mobile push notifications
- **[Security](./security.md)** — Privacy and data protection

85
docs/docker.md Normal file
View File

@@ -0,0 +1,85 @@
# 🐳 Docker Guide
<div align="center">
**⚡ Lightweight containerized deployment**
*Automated Microsoft Rewards with minimal Docker footprint*
</div>
---
## 🚀 Quick Start
### **Prerequisites**
- ✅ `src/accounts.json` configured with your Microsoft accounts
- ✅ `src/config.json` exists (uses defaults if not customized)
- ✅ Docker & Docker Compose installed
### **Launch**
```bash
# Build and start the container
docker compose up -d
# Monitor the automation
docker logs -f microsoft-rewards-script
# Stop when needed
docker compose down
```
**That's it!** The container runs the built-in scheduler automatically.uide
This project ships with a Docker setup tailored for headless runs. It uses Playwright’s Chromium Headless Shell to keep the image small.
## Quick Start
- Ensure you have `src/accounts.json` and `src/config.json` in the repo
- Build and start:
- `docker compose up -d`
- Follow logs:
- `docker logs -f microsoft-rewards-script`
## Volumes & Files
The compose file mounts:
- `./src/accounts.json` → `/usr/src/microsoft-rewards-script/accounts.json` (read‑only)
- `./src/config.json` → `/usr/src/microsoft-rewards-script/config.json` (read‑only)
- `./sessions` → `/usr/src/microsoft-rewards-script/sessions` (persist login sessions)
You can also use env overrides supported by the app loader:
- `ACCOUNTS_FILE=/path/to/accounts.json`
- `ACCOUNTS_JSON='[ {"email":"...","password":"..."} ]'`
## Environment
Useful variables:
- `TZ` — container time zone (e.g., `Europe/Paris`)
- `NODE_ENV=production`
- `FORCE_HEADLESS=1` — ensures headless mode inside the container
- Scheduler knobs (optional):
- `SCHEDULER_DAILY_JITTER_MINUTES_MIN` / `SCHEDULER_DAILY_JITTER_MINUTES_MAX`
- `SCHEDULER_PASS_TIMEOUT_MINUTES`
- `SCHEDULER_FORK_PER_PASS`
## Headless Browsers
The Docker image installs only Chromium Headless Shell via:
- `npx playwright install --with-deps --only-shell`
This dramatically reduces image size vs. installing all Playwright browsers.
## One‑shot vs. Scheduler
- Default command runs the built‑in scheduler: `npm run start:schedule`
- For one‑shot run, override the command:
- `docker run --rm ... node ./dist/index.js`
## Tips
- If you see 2FA prompts, add your TOTP Base32 secret to `accounts.json` so the bot can auto‑fill codes.
- Use a persistent `sessions` volume to avoid re‑logging every run.
- For proxies per account, fill the `proxy` block in your `accounts.json` (see [Proxy](./proxy.md)).
---
## 🔗 Related Guides
- **[Getting Started](./getting-started.md)** — Initial setup before containerization
- **[Accounts & 2FA](./accounts.md)** — Configure accounts for Docker
- **[Scheduler](./schedule.md)** — Alternative to Docker cron automation
- **[Proxy Configuration](./proxy.md)** — Network routing in containers

136
docs/getting-started.md Normal file
View File

@@ -0,0 +1,136 @@
# 🚀 Getting Started
<div align="center">
**🎯 From zero to earning Microsoft Rewards points in minutes**
*Complete setup guide for beginners*
</div>
---
## ✅ Requirements
- **Node.js 18+** (22 recommended) — [Download here](https://nodejs.org/)
- **Microsoft accounts** with email + password
- **Optional:** Docker for containerized deployment
---
## ⚡ Quick Setup (Recommended)
<div align="center">
### **🎬 One Command, Total Automation**
</div>
```bash
# 🪟 Windows
setup/setup.bat
# 🐧 Linux/macOS/WSL
bash setup/setup.sh
# 🌍 Any platform
npm run setup
```
**That's it!** The wizard will:
- ✅ Help you create `src/accounts.json` with your Microsoft credentials
- ✅ Install all dependencies automatically
- ✅ Build the TypeScript project
- ✅ Start earning points immediately
---
## 🛠️ Manual Setup
<details>
<summary><strong>📖 Prefer step-by-step? Click here</strong></summary>
### 1️⃣ **Configure Your Accounts**
```bash
cp src/accounts.example.json src/accounts.json
# Edit accounts.json with your Microsoft credentials
```
### 2️⃣ **Install Dependencies & Build**
```bash
npm install
npm run build
```
### 3️⃣ **Choose Your Mode**
```bash
# Single run (test it works)
npm start
# Automated daily scheduler (set and forget)
npm run start:schedule
```
</details>
---
## 🎯 What Happens Next?
The script will automatically:
- 🔍 **Search Bing** for points (desktop + mobile)
- 📅 **Complete daily sets** (quizzes, polls, activities)
- 🎁 **Grab promotions** and bonus opportunities
- 🃏 **Work on punch cards** (multi-day challenges)
- ✅ **Daily check-ins** for easy points
- 📚 **Read articles** for additional rewards
**All while looking completely natural to Microsoft!** 🤖
---
## 🐳 Docker Alternative
If you prefer containers:
```bash
# Ensure accounts.json and config.json exist
docker compose up -d
# Follow logs
docker logs -f microsoft-rewards-script
```
**[Full Docker Guide →](./docker.md)**
---
## 🔧 Next Steps
Once running, explore these guides:
| Priority | Guide | Why Important |
|----------|-------|---------------|
| **High** | **[Accounts & 2FA](./accounts.md)** | Set up TOTP for secure automation |
| **High** | **[Scheduling](./schedule.md)** | Configure automated daily runs |
| **Medium** | **[Notifications](./ntfy.md)** | Get alerts on your phone |
| **Low** | **[Humanization](./humanization.md)** | Advanced anti-detection |
---
## 🆘 Need Help?
**Script not starting?** → [Troubleshooting Guide](./diagnostics.md)
**Login issues?** → [Accounts & 2FA Setup](./accounts.md)
**Want Docker?** → [Container Guide](./docker.md)
**Found a bug?** [Report it here](https://github.com/TheNetsky/Microsoft-Rewards-Script/issues)
**Need support?** [Join our Discord](https://discord.gg/KRBFxxsU)
---
## 🔗 Related Guides
- **[Accounts & 2FA](./accounts.md)** — Add Microsoft accounts with TOTP
- **[Docker](./docker.md)** — Deploy with containers
- **[Scheduler](./schedule.md)** — Automate daily execution
- **[Discord Webhooks](./conclusionwebhook.md)** — Get run summaries

277
docs/humanization.md Normal file
View File

@@ -0,0 +1,277 @@
# 🤖 Humanization (Human Mode)
<div align="center">
**🎭 Natural automation that mimics human behavior**
*Subtle gestures for safer operation*
</div>
---
## 🎯 What is Humanization?
Human Mode adds **subtle human-like behavior** to make your automation look and feel more natural. It's designed to be **safe by design** with minimal, realistic gestures.
### **Key Features**
- 🎲 **Random delays** — Natural pause variation
- 🖱️ **Micro movements** — Subtle mouse gestures
- 📜 **Tiny scrolls** — Minor page adjustments
- ⏰ **Time windows** — Run during specific hours
- 📅 **Random off days** — Skip days naturally
- 🔒 **Safe by design** — Never clicks random elements
---
## ⚙️ Configuration
### **Simple Setup (Recommended)**
```json
{
"humanization": {
"enabled": true
}
}
```
### **Advanced Configuration**
```json
{
"humanization": {
"enabled": true,
"actionDelay": { "min": 150, "max": 450 },
"gestureMoveProb": 0.4,
"gestureScrollProb": 0.2,
"allowedWindows": ["08:00-10:30", "20:00-22:30"],
"randomOffDaysPerWeek": 1
}
}
```
### **Configuration Options**
| Setting | Default | Description |
|---------|---------|-------------|
| `enabled` | `true` | Master toggle for all humanization |
| `actionDelay` | `{min: 150, max: 450}` | Random pause between actions (ms) |
| `gestureMoveProb` | `0.4` | Probability (0-1) for tiny mouse moves |
| `gestureScrollProb` | `0.2` | Probability (0-1) for minor scrolls |
| `allowedWindows` | `[]` | Time windows for script execution |
| `randomOffDaysPerWeek` | `1` | Skip N random days per week |
---
## 🎭 How It Works
### **Action Delays**
- **Random pauses** between automation steps
- **Natural variation** mimics human decision time
- **Configurable range** allows fine-tuning
### **Gesture Simulation**
- **Micro mouse moves** — Tiny cursor adjustments (safe zones only)
- **Minor scrolls** — Small page movements (non-interactive areas)
- **Probability-based** — Not every action includes gestures
### **Temporal Patterns**
- **Time windows** — Only run during specified hours
- **Random off days** — Skip days to avoid rigid patterns
- **Natural scheduling** — Mimics human usage patterns
---
## 🎯 Usage Examples
### **Default Setup (Recommended)**
```json
{
"humanization": { "enabled": true }
}
```
✅ **Best for most users** — Balanced safety and naturalness
### **Minimal Humanization**
```json
{
"humanization": {
"enabled": true,
"gestureMoveProb": 0.1,
"gestureScrollProb": 0.1,
"actionDelay": { "min": 100, "max": 200 }
}
}
```
⚡ **Faster execution** with minimal gestures
### **Maximum Natural Behavior**
```json
{
"humanization": {
"enabled": true,
"actionDelay": { "min": 300, "max": 800 },
"gestureMoveProb": 0.6,
"gestureScrollProb": 0.4,
"allowedWindows": ["08:30-11:00", "19:00-22:00"],
"randomOffDaysPerWeek": 2
}
}
```
🎭 **Most human-like** but slower execution
### **Disabled Humanization**
```json
{
"humanization": { "enabled": false }
}
```
🚀 **Fastest execution** — automation optimized
---
## ⏰ Time Windows
### **Setup**
```json
{
"humanization": {
"enabled": true,
"allowedWindows": ["08:00-10:30", "20:00-22:30"]
}
}
```
### **Behavior**
- Script **waits** until next allowed window
- Uses **local time** for scheduling
- **Multiple windows** supported per day
- **Empty array** `[]` = no time restrictions
### **Examples**
```json
// Morning and evening windows
"allowedWindows": ["08:00-10:30", "20:00-22:30"]
// Lunch break only
"allowedWindows": ["12:00-13:00"]
// Extended evening window
"allowedWindows": ["18:00-23:00"]
// No restrictions
"allowedWindows": []
```
---
## 📅 Random Off Days
### **Purpose**
Mimics natural human behavior by skipping random days per week.
### **Configuration**
```json
{
"humanization": {
"randomOffDaysPerWeek": 1 // Skip 1 random day per week
}
}
```
### **Options**
- `0` — Never skip days
- `1` — Skip 1 random day per week (default)
- `2` — Skip 2 random days per week
- `3+` — Higher values for more irregular patterns
---
## 🔒 Safety Features
### **Safe by Design**
- ✅ **Never clicks** arbitrary elements
- ✅ **Gestures only** in safe zones
- ✅ **Minor movements** — pixel-level adjustments
- ✅ **Probability-based** — Natural randomness
- ✅ **Non-interactive areas** — Avoids clickable elements
### **Buy Mode Compatibility**
- **Passive monitoring** remains unaffected
- **No interference** with manual actions
- **Background tasks** only for monitoring
---
## 📊 Performance Impact
| Setting | Speed Impact | Natural Feel | Recommendation |
|---------|--------------|--------------|----------------|
| **Disabled** | Fastest | Robotic | Development only |
| **Default** | Moderate | Balanced | **Recommended** |
| **High probability** | Slower | Very natural | Conservative users |
| **Time windows** | Delayed start | Realistic | Scheduled execution |
---
## 🛠️ Troubleshooting
| Problem | Solution |
|---------|----------|
| **Script too slow** | Reduce `actionDelay` values; lower probabilities |
| **Too robotic** | Increase probabilities; add time windows |
| **Runs outside hours** | Check `allowedWindows` format (24-hour time) |
| **Skipping too many days** | Reduce `randomOffDaysPerWeek` |
| **Gestures interfering** | Lower probabilities or disable specific gestures |
### **Debug Humanization**
```powershell
$env:DEBUG_HUMANIZATION=1; npm start
```
---
## 🎛️ Presets
### **Conservative**
```json
{
"humanization": {
"enabled": true,
"actionDelay": { "min": 200, "max": 600 },
"gestureMoveProb": 0.6,
"gestureScrollProb": 0.4,
"allowedWindows": ["08:00-10:00", "20:00-22:00"],
"randomOffDaysPerWeek": 2
}
}
```
### **Balanced (Default)**
```json
{
"humanization": {
"enabled": true
}
}
```
### **Performance**
```json
{
"humanization": {
"enabled": true,
"actionDelay": { "min": 100, "max": 250 },
"gestureMoveProb": 0.2,
"gestureScrollProb": 0.1,
"randomOffDaysPerWeek": 0
}
}
```
---
## 🔗 Related Guides
- **[Getting Started](./getting-started.md)** — Initial setup and configuration
- **[Scheduler](./schedule.md)** — Automated timing and execution
- **[Security](./security.md)** — Privacy and detection avoidance
- **[Buy Mode](./buy-mode.md)** — Manual purchasing with monitoring

96
docs/index.md Normal file
View File

@@ -0,0 +1,96 @@
# 📚 Microsoft Rewards Script V2 Documentation
<div align="center">
**🎯 Your complete guide to automating Microsoft Rewards**
*Everything you need to get started and master the script*
</div>
---
## 🚀 Quick Navigation
### **Essential Setup**
| Guide | Description |
|-------|-------------|
| **[🎬 Getting Started](./getting-started.md)** | Zero to running — complete setup guide |
| **[👤 Accounts & 2FA](./accounts.md)** | Microsoft accounts + TOTP authentication |
| **[🐳 Docker](./docker.md)** | Container deployment with headless browsers |
### **Operations & Advanced**
| Guide | Description |
|-------|-------------|
| **[⏰ Scheduling](./schedule.md)** | Automated daily runs and timing |
| **[🛠️ Diagnostics](./diagnostics.md)** | Troubleshooting and error capture |
| **[🧠 Humanization](./humanization.md)** | Anti-detection and natural behavior |
| **[🌐 Proxy Setup](./proxy.md)** | Network routing and IP management |
| **[⚙️ Configuration Reference](./config.md)** | Full `config.json` field documentation |
### **Notifications & Monitoring**
| Guide | Description |
|-------|-------------|
| **[📱 NTFY Push](./ntfy.md)** | Mobile push notifications |
| **[🔗 Discord Webhooks](./conclusionwebhook.md)** | Rich server notifications |
### **Special Modes**
| Guide | Description |
|-------|-------------|
| **[💳 Buy Mode](./buy-mode.md)** | Manual redemption with live monitoring |
---
## 🎯 Recommended Reading Path
**New Users:** Getting Started → Accounts & 2FA → Choose Docker OR Scheduling
**Advanced Users:** Humanization → Diagnostics → Notifications
**Docker Users:** Getting Started → Accounts & 2FA → Docker → NTFY/Webhookstion Index
Welcome to the Microsoft Rewards Script V2 docs. Start here:
- Getting Started: high‑level setup from zero to running — [Getting Started](./getting-started.md)
- Accounts & Authentication — [Accounts & TOTP (2FA)](./accounts.md)
- Runtime & Operations — [Docker Guide](./docker.md), [Scheduling](./schedule.md), [Diagnostics](./diagnostics.md), [Humanization](./humanization.md), [Job State](./jobstate.md), [Auto Update](./update.md), [Security](./security.md)
- Notifications — [NTFY Push](./ntfy.md), [Conclusion Webhook (Discord)](./conclusionwebhook.md)
- Modes & Activities — [Buy Mode](./buy-mode.md)
Recommended reading order if you’re new: Getting Started → Accounts & TOTP → Docker or Scheduler.# Documentation Index
Welcome to the Microsoft Rewards Script V2 documentation. Start here to set up your environment, add your Microsoft accounts, and understand how the bot operates.
- Getting Started: High‑level setup from zero to running
- [Getting Started](./getting-started.md)
- Accounts & Authentication
- [Accounts & TOTP (2FA)](./accounts.md)
- [Proxy Setup](./proxy.md)
- Runtime & Operations
- [Docker Guide](./docker.md)
- [Scheduling](./schedule.md)
- [Diagnostics](./diagnostics.md)
- [Humanization](./humanization.md)
- [Job State](./jobstate.md)
- [Auto Update](./update.md)
- [Security Notes](./security.md)
- Notifications
- [NTFY Push](./ntfy.md)
- [Conclusion Webhook (Discord)](./conclusionwebhook.md)
- Modes & Activities
- [Buy Mode](./buy-mode.md)
If you are new, read Getting Started first, then Accounts & TOTP.
---
## 🚀 Quick Start Path
**New users should follow this sequence:**
1. **[Getting Started](./getting-started.md)** — Install and basic configuration
2. **[Accounts & 2FA](./accounts.md)** — Add your Microsoft accounts
3. **[Docker](./docker.md)** OR **[Scheduler](./schedule.md)** — Choose deployment method
4. **[NTFY](./ntfy.md)** OR **[Discord Webhooks](./conclusionwebhook.md)** — Set up notifications
**Advanced users may also need:**
- **[Proxy](./proxy.md)** — For privacy and geographic routing
- **[Security](./security.md)** — Account protection and incident response
- **[Humanization](./humanization.md)** — Natural behavior simulation

339
docs/jobstate.md Normal file
View File

@@ -0,0 +1,339 @@
# 💾 Job State Persistence
<div align="center">
**🔄 Resume interrupted tasks and track progress across runs**
*Never lose your progress again*
</div>
---
## 🎯 What is Job State Persistence?
Job state persistence allows the script to **resume interrupted tasks** and **track progress** across multiple runs, ensuring no work is lost when the script is stopped or crashes.
### **Key Features**
- 🔄 **Resumable tasks** — Pick up exactly where you left off
- 📅 **Daily tracking** — Date-specific progress monitoring
- 👤 **Per-account isolation** — Independent progress for each account
- 🛡️ **Corruption protection** — Atomic writes prevent data loss
- 🚀 **Performance optimized** — Minimal overhead
---
## ⚙️ Configuration
### **Basic Setup**
```json
{
"jobState": {
"enabled": true,
"dir": ""
}
}
```
### **Configuration Options**
| Setting | Description | Default |
|---------|-------------|---------|
| `enabled` | Enable job state persistence | `true` |
| `dir` | Custom directory for state files | `""` (uses `sessions/job-state`) |
---
## 🏗️ How It Works
### **State Tracking**
- 📋 **Monitors completion** status of individual activities
- 🔍 **Tracks progress** for daily sets, searches, and promotional tasks
- ❌ **Prevents duplicates** when script restarts
### **Storage Structure**
```
sessions/job-state/
├── account1@email.com/
│ ├── daily-set-2025-01-20.json
│ ├── desktop-search-2025-01-20.json
│ └── mobile-search-2025-01-20.json
└── account2@email.com/
├── daily-set-2025-01-20.json
└── promotional-tasks-2025-01-20.json
```
### **State File Format**
```json
{
"date": "2025-01-20",
"account": "user@email.com",
"type": "daily-set",
"completed": [
"daily-check-in",
"quiz-1",
"poll-1"
],
"remaining": [
"quiz-2",
"search-desktop"
],
"lastUpdate": "2025-01-20T10:30:00.000Z"
}
```
---
## 🚀 Key Benefits
### **Resumable Tasks**
- ✅ **Script restarts** pick up where they left off
- ✅ **Individual completion** is remembered
- ✅ **Avoid re-doing** completed activities
### **Daily Reset**
- 📅 **Date-specific** state files
- 🌅 **New day** automatically starts fresh tracking
- 📚 **History preserved** for analysis
### **Account Isolation**
- 👤 **Separate state** per account
- ⚡ **Parallel processing** doesn't interfere
- 📊 **Independent progress** tracking
---
## 📋 Use Cases
### **Interrupted Executions**
| Scenario | Benefit |
|----------|---------|
| **Network issues** | Resume when connection restored |
| **System reboots** | Continue after restart |
| **Manual termination** | Pick up from last checkpoint |
| **Resource exhaustion** | Recover without losing progress |
### **Selective Reruns**
| Feature | Description |
|---------|-------------|
| **Skip completed sets** | Avoid redoing finished daily activities |
| **Resume searches** | Continue partial search sessions |
| **Retry failed tasks** | Target only problematic activities |
| **Account targeting** | Process specific accounts only |
### **Progress Monitoring**
- 📊 **Track completion rates** across accounts
- 🔍 **Identify problematic** activities
- ⏱️ **Monitor task duration** trends
- 🐛 **Debug stuck** or slow tasks
---
## 🛠️ Technical Implementation
### **Checkpoint Strategy**
- 💾 **State saved** after each completed activity
- ⚛️ **Atomic writes** prevent corruption
- 🔒 **Lock-free design** for concurrent access
### **Performance Optimization**
- ⚡ **Minimal I/O overhead** — Fast state updates
- 🧠 **In-memory caching** — Reduce disk access
- 📥 **Lazy loading** — Load state files on demand
### **Error Handling**
- 🔧 **Corrupted files** are rebuilt automatically
- 📁 **Missing directories** created as needed
- 🎯 **Graceful degradation** when disabled
---
## 🗂️ File Management
### **Automatic Behavior**
- 📅 **Date-specific files** — New files for each day
- 💾 **Preserved history** — Old files remain for reference
- 🚀 **No auto-deletion** — Manual cleanup recommended
### **Manual Maintenance**
```powershell
# Clean state files older than 7 days
Get-ChildItem sessions/job-state -Recurse -Filter "*.json" | Where-Object {$_.LastWriteTime -lt (Get-Date).AddDays(-7)} | Remove-Item
# Reset all job state (start fresh)
Remove-Item -Recurse -Force sessions/job-state/
# Reset specific account state
Remove-Item -Recurse -Force sessions/job-state/user@email.com/
```
---
## 📊 Example Workflows
### **Interrupted Daily Run**
```
Day 1 - 10:30 AM:
✅ Account A: Daily set completed
🔄 Account B: 3/5 daily tasks done
❌ Script crashes
Day 1 - 2:00 PM:
🚀 Script restarts
✅ Account A: Skipped (already complete)
🔄 Account B: Resumes with 2 remaining tasks
```
### **Multi-Day Tracking**
```
Monday:
📅 daily-set-2025-01-20.json created
✅ All tasks completed
Tuesday:
📅 daily-set-2025-01-21.json created
🔄 Fresh start for new day
📚 Monday's progress preserved
```
---
## 🔍 Debugging Job State
### **State Inspection**
```powershell
# View current state for account
Get-Content sessions/job-state/user@email.com/daily-set-2025-01-20.json | ConvertFrom-Json
# List all state files
Get-ChildItem sessions/job-state -Recurse -Filter "*.json"
```
### **Debug Output**
Enable verbose logging to see state operations:
```powershell
$env:DEBUG_REWARDS_VERBOSE=1; npm start
```
Sample output:
```
[INFO] Loading job state for user@email.com (daily-set)
[INFO] Found 3 completed tasks, 2 remaining
[INFO] Skipping completed task: daily-check-in
[INFO] Starting task: quiz-2
```
---
## 🛠️ Troubleshooting
| Problem | Cause | Solution |
|---------|-------|----------|
| **Tasks not resuming** | Missing/corrupt state files | Check file permissions; verify directory exists |
| **Duplicate execution** | Clock sync issues | Ensure system time is accurate |
| **Excessive files** | No cleanup schedule | Implement regular state file cleanup |
| **Permission errors** | Write access denied | Verify sessions/ directory is writable |
### **Common Issues**
#### **Tasks Not Resuming**
```
[ERROR] Failed to load job state: Permission denied
```
**Solutions:**
- ✅ Check file/directory permissions
- ✅ Verify state directory exists
- ✅ Ensure write access to sessions/
#### **Duplicate Task Execution**
```
[WARN] Task appears to be running twice
```
**Solutions:**
- ✅ Check for corrupt state files
- ✅ Verify system clock synchronization
- ✅ Clear state for affected account
#### **Storage Growth**
```
[INFO] Job state directory: 2.3GB (1,247 files)
```
**Solutions:**
- ✅ Implement regular cleanup schedule
- ✅ Remove old state files (7+ days)
- ✅ Monitor disk space usage
---
## 🤝 Integration Features
### **Session Persistence**
- 🍪 **Works alongside** browser session storage
- 🔐 **Complements** cookie and fingerprint persistence
- 🌐 **Independent of** proxy and authentication state
### **Clustering**
- ⚡ **Isolated state** per cluster worker
- 🚫 **No shared state** between parallel processes
- 📁 **Worker-specific** directories
### **Scheduling**
- ⏰ **Persists across** scheduled runs
- 🌅 **Daily reset** at midnight automatically
- 🔄 **Long-running continuity** maintained
---
## ⚙️ Advanced Configuration
### **Custom State Directory**
```json
{
"jobState": {
"enabled": true,
"dir": "/custom/path/to/state"
}
}
```
### **Disabling Job State**
```json
{
"jobState": {
"enabled": false
}
}
```
**Effects when disabled:**
- ❌ **Tasks restart** from beginning each run
- ❌ **No progress tracking** between sessions
- ❌ **Potential duplicate work** on interruptions
- ✅ **Slightly faster startup** (no state loading)
---
## 📊 Best Practices
### **Development**
- ✅ **Enable for testing** — Consistent behavior
- 🧹 **Clear between changes** — Fresh state for major updates
- 🔍 **Monitor for debugging** — State files reveal execution flow
### **Production**
- ✅ **Always enabled** — Reliability is critical
- 💾 **Regular backups** — State directory backups
- 📊 **Monitor disk usage** — Prevent storage growth
### **Maintenance**
- 🗓️ **Weekly cleanup** — Remove old state files
- 🔍 **Health checks** — Verify state integrity
- 📝 **Usage monitoring** — Track storage trends
---
## 🔗 Related Guides
- **[Getting Started](./getting-started.md)** — Initial setup and configuration
- **[Scheduler](./schedule.md)** — Automated timing and execution
- **[Diagnostics](./diagnostics.md)** — Error capture and debugging
- **[Security](./security.md)** — Privacy and data protection

407
docs/ntfy.md Normal file
View File

@@ -0,0 +1,407 @@
# 📱 NTFY Push Notifications
<div align="center">
**🔔 Real-time push notifications to your devices**
*Stay informed wherever you are*
</div>
---
## 🎯 What is NTFY?
NTFY is a **simple HTTP-based pub-sub notification service** that sends push notifications to your phone, desktop, or web browser. Perfect for real-time alerts about script events and errors.
### **Key Features**
- 📱 **Mobile & Desktop** — Push to any device
- 🆓 **Free & Open Source** — No vendor lock-in
- 🏠 **Self-hostable** — Complete privacy control
- ⚡ **Real-time delivery** — Instant notifications
- 🔒 **Authentication support** — Secure topics
### **Official Links**
- **Website** — [ntfy.sh](https://ntfy.sh)
- **Documentation** — [docs.ntfy.sh](https://docs.ntfy.sh)
- **GitHub** — [binwiederhier/ntfy](https://github.com/binwiederhier/ntfy)
---
## ⚙️ Configuration
### **Basic Setup**
```json
{
"notifications": {
"ntfy": {
"enabled": true,
"url": "https://ntfy.sh",
"topic": "rewards-script",
"authToken": ""
}
}
}
```
### **Configuration Options**
| Setting | Description | Example |
|---------|-------------|---------|
| `enabled` | Enable NTFY notifications | `true` |
| `url` | NTFY server URL | `"https://ntfy.sh"` |
| `topic` | Notification topic name | `"rewards-script"` |
| `authToken` | Authentication token (optional) | `"tk_abc123..."` |
---
## 🚀 Setup Options
### **Option 1: Public Service (Easiest)**
```json
{
"notifications": {
"ntfy": {
"enabled": true,
"url": "https://ntfy.sh",
"topic": "your-unique-topic-name"
}
}
}
```
**Pros:**
- ✅ No server setup required
- ✅ Always available
- ✅ Free to use
**Cons:**
- ❌ Public server (less privacy)
- ❌ Rate limits apply
- ❌ Dependent on external service
### **Option 2: Self-Hosted (Recommended)**
```json
{
"notifications": {
"ntfy": {
"enabled": true,
"url": "https://ntfy.yourdomain.com",
"topic": "rewards",
"authToken": "tk_your_token_here"
}
}
}
```
**Self-Hosted Setup:**
```yaml
# docker-compose.yml
version: '3.8'
services:
ntfy:
image: binwiederhier/ntfy
container_name: ntfy
ports:
- "80:80"
volumes:
- ./data:/var/lib/ntfy
command: serve
```
---
## 🔒 Authentication
### **When You Need Auth**
Authentication tokens are **optional** but required for:
- 🔐 **Private topics** with username/password
- 🏠 **Private NTFY servers** with authentication
- 🛡️ **Preventing spam** on your topic
### **Getting an Auth Token**
#### **Method 1: Command Line**
```bash
ntfy token
```
#### **Method 2: Web Interface**
1. Visit your NTFY server (e.g., `https://ntfy.sh`)
2. Go to **Account** section
3. Generate **new access token**
#### **Method 3: API**
```bash
curl -X POST -d '{"label":"rewards-script"}' \
-H "Authorization: Bearer YOUR_LOGIN_TOKEN" \
https://ntfy.sh/v1/account/tokens
```
### **Token Format**
- Tokens start with `tk_` (e.g., `tk_abc123def456...`)
- Use Bearer authentication format
- Tokens are permanent until revoked
---
## 📲 Receiving Notifications
### **Mobile Apps**
- **Android** — [NTFY on Google Play](https://play.google.com/store/apps/details?id=io.heckel.ntfy)
- **iOS** — [NTFY on App Store](https://apps.apple.com/app/ntfy/id1625396347)
- **F-Droid** — Available for Android
### **Desktop Options**
- **Web Interface** — Visit your NTFY server URL
- **Desktop Apps** — Available for Linux, macOS, Windows
- **Browser Extension** — Chrome/Firefox extensions
### **Setup Steps**
1. **Install** NTFY app on your device
2. **Add subscription** to your topic name
3. **Enter server URL** (if self-hosted)
4. **Test** with a manual message
---
## 🔔 Notification Types
### **Error Notifications**
**Priority:** Max 🚨 | **Trigger:** Script errors and failures
```
[ERROR] DESKTOP [LOGIN] Failed to login: Invalid credentials
```
### **Warning Notifications**
**Priority:** High ⚠️ | **Trigger:** Important warnings
```
[WARN] MOBILE [SEARCH] Didn't gain expected points from search
```
### **Info Notifications**
**Priority:** Default 🏆 | **Trigger:** Important milestones
```
[INFO] MAIN [TASK] Started tasks for account user@email.com
```
### **Buy Mode Notifications**
**Priority:** High 💳 | **Trigger:** Point spending detected
```
💳 Spend detected (Buy Mode)
Account: user@email.com
Spent: -500 points
Current: 12,500 points
Session spent: 1,200 points
```
### **Conclusion Summary**
**End-of-run summary with rich formatting:**
```
🎯 Microsoft Rewards Summary
Accounts: 3 • 0 with issues
Total: 15,230 -> 16,890 (+1,660)
Average Duration: 8m 32s
Cumulative Runtime: 25m 36s
```
---
## 🤝 Integration with Discord
### **Complementary Setup**
Use **both** NTFY and Discord for comprehensive monitoring:
```json
{
"notifications": {
"webhook": {
"enabled": true,
"url": "https://discord.com/api/webhooks/..."
},
"conclusionWebhook": {
"enabled": true,
"url": "https://discord.com/api/webhooks/..."
},
"ntfy": {
"enabled": true,
"url": "https://ntfy.sh",
"topic": "rewards-script"
}
}
}
```
### **Coverage Comparison**
| Feature | NTFY | Discord |
|---------|------|---------|
| **Mobile push** | ✅ Instant | ❌ App required |
| **Rich formatting** | ❌ Text only | ✅ Embeds + colors |
| **Desktop alerts** | ✅ Native | ✅ App notifications |
| **Offline delivery** | ✅ Queued | ❌ Real-time only |
| **Self-hosted** | ✅ Easy | ❌ Complex |
---
## 🎛️ Advanced Configuration
### **Custom Topic Names**
Use descriptive, unique topic names:
```json
{
"topic": "rewards-production-server1"
}
{
"topic": "msn-rewards-home-pc"
}
{
"topic": "rewards-dev-testing"
}
```
### **Environment-Specific**
```json
{
"notifications": {
"ntfy": {
"enabled": true,
"url": "https://ntfy.internal.lan",
"topic": "homelab-rewards",
"authToken": "tk_homelab_token"
}
}
}
```
---
## 🧪 Testing & Debugging
### **Manual Test Message**
```bash
# Public server (no auth)
curl -d "Test message from rewards script" https://ntfy.sh/your-topic
# With authentication
curl -H "Authorization: Bearer tk_your_token" \
-d "Authenticated test message" \
https://ntfy.sh/your-topic
```
### **Script Debug Mode**
```powershell
$env:DEBUG_REWARDS_VERBOSE=1; npm start
```
### **Server Health Check**
```bash
# Check NTFY server status
curl -s https://ntfy.sh/v1/health
# List your topics (with auth)
curl -H "Authorization: Bearer tk_your_token" \
https://ntfy.sh/v1/account/topics
```
---
## 🛠️ Troubleshooting
| Problem | Solution |
|---------|----------|
| **No notifications** | Check topic spelling; verify app subscription |
| **Auth failures** | Verify token format (`tk_`); check token validity |
| **Wrong server** | Test server URL in browser; check HTTPS/HTTP |
| **Rate limits** | Switch to self-hosted; reduce notification frequency |
### **Common Fixes**
- ✅ **Topic name** — Must match exactly between config and app
- ✅ **Server URL** — Include `https://` and check accessibility
- ✅ **Token format** — Must start with `tk_` for authentication
- ✅ **Network** — Verify firewall/proxy settings
---
## 🏠 Homelab Integration
### **Official Support**
NTFY is included in:
- **Debian Trixie** (testing)
- **Ubuntu** (latest versions)
### **Popular Integrations**
- **Sonarr/Radarr** — Download completion notifications
- **Prometheus** — Alert manager integration
- **Home Assistant** — Automation notifications
- **Portainer** — Container status alerts
### **Docker Stack Example**
```yaml
version: '3.8'
services:
ntfy:
image: binwiederhier/ntfy
container_name: ntfy
ports:
- "80:80"
volumes:
- ./ntfy-data:/var/lib/ntfy
environment:
- NTFY_BASE_URL=https://ntfy.yourdomain.com
command: serve
rewards:
build: .
depends_on:
- ntfy
environment:
- NTFY_URL=http://ntfy:80
```
---
## 🔒 Privacy & Security
### **Public Server (ntfy.sh)**
- ⚠️ Messages pass through public infrastructure
- ⚠️ Topic names visible in logs
- ✅ Suitable for non-sensitive notifications
### **Self-Hosted Server**
- ✅ Complete control over data
- ✅ Private network deployment possible
- ✅ Recommended for sensitive information
### **Best Practices**
- 🔐 Use **unique, non-guessable** topic names
- 🔑 Enable **authentication** for sensitive notifications
- 🏠 Use **self-hosted server** for maximum privacy
- 🔄 **Regularly rotate** authentication tokens
### **Data Retention**
- 📨 Messages are **not permanently stored**
- ⏱️ Delivery attempts **retried** for short periods
- 🗑️ **No long-term** message history
---
## ⚡ Performance Impact
### **Script Performance**
- ✅ **Minimal overhead** — Fire-and-forget notifications
- ✅ **Non-blocking** — Failed notifications don't affect script
- ✅ **Asynchronous** — No execution delays
### **Network Usage**
- 📊 **Low bandwidth** — Text-only messages
- ⚡ **HTTP POST** — Simple, efficient protocol
- 🔄 **Retry logic** — Automatic failure recovery
---
## 🔗 Related Guides
- **[Discord Webhooks](./conclusionwebhook.md)** — Rich notification embeds
- **[Getting Started](./getting-started.md)** — Initial setup and configuration
- **[Buy Mode](./buy-mode.md)** — Manual purchasing notifications
- **[Security](./security.md)** — Privacy and data protection

611
docs/proxy.md Normal file
View File

@@ -0,0 +1,611 @@
# 🌐 Proxy Configuration
<div align="center">
**🔒 Route traffic through proxy servers for privacy and flexibility**
*Enhanced anonymity and geographic control*
</div>
---
## 🎯 What Are Proxies?
Proxies act as **intermediaries** between your script and Microsoft's servers, providing enhanced privacy, geographic flexibility, and network management capabilities.
### **Key Benefits**
- 🎭 **IP masking** — Hide your real IP address
- 🌍 **Geographic flexibility** — Appear to browse from different locations
- ⚡ **Rate limiting** — Distribute requests across multiple IPs
- 🔧 **Network control** — Route traffic through specific servers
- 🔒 **Privacy enhancement** — Add layer of anonymity
---
## ⚙️ Configuration
### **Basic Setup**
```json
{
"browser": {
"proxy": {
"enabled": false,
"server": "proxy.example.com:8080",
"username": "",
"password": "",
"bypass": []
}
}
}
```
### **Configuration Options**
| Setting | Description | Example |
|---------|-------------|---------|
| `enabled` | Enable proxy usage | `true` |
| `server` | Proxy server address and port | `"proxy.example.com:8080"` |
| `username` | Proxy authentication username | `"proxyuser"` |
| `password` | Proxy authentication password | `"proxypass123"` |
| `bypass` | Domains to bypass proxy | `["localhost", "*.internal.com"]` |
---
## 🔌 Supported Proxy Types
### **HTTP Proxies**
**Most common type for web traffic**
```json
{
"browser": {
"proxy": {
"enabled": true,
"server": "http://proxy.example.com:8080",
"username": "user",
"password": "pass"
}
}
}
```
### **HTTPS Proxies**
**Encrypted proxy connections**
```json
{
"browser": {
"proxy": {
"enabled": true,
"server": "https://secure-proxy.example.com:8080",
"username": "user",
"password": "pass"
}
}
}
```
### **SOCKS Proxies**
**Support for SOCKS4 and SOCKS5**
```json
{
"browser": {
"proxy": {
"enabled": true,
"server": "socks5://socks-proxy.example.com:1080",
"username": "user",
"password": "pass"
}
}
}
```
---
## 🏢 Popular Proxy Providers
### **Residential Proxies (Recommended)**
**High-quality IPs from real devices**
#### **Top Providers**
- **Bright Data** (formerly Luminati) — Premium quality
- **Smartproxy** — User-friendly dashboard
- **Oxylabs** — Enterprise-grade
- **ProxyMesh** — Developer-focused
#### **Configuration Example**
```json
{
"browser": {
"proxy": {
"enabled": true,
"server": "rotating-residential.brightdata.com:22225",
"username": "customer-username-session-random",
"password": "your-password"
}
}
}
```
### **Datacenter Proxies**
**Fast and affordable server-based IPs**
#### **Popular Providers**
- **SquidProxies** — Reliable performance
- **MyPrivateProxy** — Dedicated IPs
- **ProxyRack** — Budget-friendly
- **Storm Proxies** — Rotating options
#### **Configuration Example**
```json
{
"browser": {
"proxy": {
"enabled": true,
"server": "datacenter.squidproxies.com:8080",
"username": "username",
"password": "password"
}
}
}
```
### **Free Proxies**
**⚠️ Not recommended for production use**
#### **Risks**
- ❌ Unreliable connections
- ❌ Potential security issues
- ❌ Often blocked by services
- ❌ Poor performance
---
## 🔐 Authentication Methods
### **Username/Password (Most Common)**
```json
{
"browser": {
"proxy": {
"enabled": true,
"server": "proxy.example.com:8080",
"username": "your-username",
"password": "your-password"
}
}
}
```
### **IP Whitelisting**
```json
{
"browser": {
"proxy": {
"enabled": true,
"server": "proxy.example.com:8080",
"username": "",
"password": ""
}
}
}
```
**Setup Steps:**
1. Contact proxy provider
2. Provide your server's IP address
3. Configure whitelist in provider dashboard
4. Remove credentials from config
### **Session-Based Authentication**
```json
{
"browser": {
"proxy": {
"enabled": true,
"server": "session-proxy.example.com:8080",
"username": "customer-session-sticky123",
"password": "your-password"
}
}
}
```
---
## 🚫 Bypass Configuration
### **Local Development**
**Bypass proxy for local services**
```json
{
"browser": {
"proxy": {
"enabled": true,
"server": "proxy.example.com:8080",
"bypass": [
"localhost",
"127.0.0.1",
"*.local",
"*.internal"
]
}
}
}
```
### **Specific Domains**
**Route certain domains directly**
```json
{
"browser": {
"proxy": {
"enabled": true,
"server": "proxy.example.com:8080",
"bypass": [
"*.microsoft.com",
"login.live.com",
"account.microsoft.com"
]
}
}
}
```
### **Advanced Patterns**
```json
{
"browser": {
"proxy": {
"enabled": true,
"server": "proxy.example.com:8080",
"bypass": [
"*.intranet.*",
"192.168.*.*",
"10.*.*.*",
"<local>"
]
}
}
}
```
---
## 🎛️ Advanced Configurations
### **Per-Account Proxies**
**Different proxies for different accounts**
```json
{
"accounts": [
{
"email": "user1@example.com",
"password": "password1",
"proxy": {
"enabled": true,
"server": "proxy1.example.com:8080"
}
},
{
"email": "user2@example.com",
"password": "password2",
"proxy": {
"enabled": true,
"server": "proxy2.example.com:8080"
}
}
]
}
```
### **Failover Configuration**
**Multiple proxy servers for redundancy**
```json
{
"browser": {
"proxy": {
"enabled": true,
"servers": [
"primary-proxy.example.com:8080",
"backup-proxy.example.com:8080",
"emergency-proxy.example.com:8080"
],
"username": "user",
"password": "pass"
}
}
}
```
### **Geographic Routing**
**Location-specific proxy selection**
```json
{
"browser": {
"proxy": {
"enabled": true,
"regions": {
"us": "us-proxy.example.com:8080",
"eu": "eu-proxy.example.com:8080",
"asia": "asia-proxy.example.com:8080"
},
"defaultRegion": "us"
}
}
}
```
---
## 🔒 Security & Environment Variables
### **Credential Protection**
**Secure proxy authentication**
**Environment Variables:**
```powershell
# Set in environment
$env:PROXY_USERNAME="your-username"
$env:PROXY_PASSWORD="your-password"
```
**Configuration:**
```json
{
"browser": {
"proxy": {
"enabled": true,
"server": "proxy.example.com:8080",
"username": "${PROXY_USERNAME}",
"password": "${PROXY_PASSWORD}"
}
}
}
```
### **HTTPS Verification**
```json
{
"browser": {
"proxy": {
"enabled": true,
"server": "proxy.example.com:8080",
"verifySSL": true,
"rejectUnauthorized": true
}
}
}
```
### **Connection Encryption**
```json
{
"browser": {
"proxy": {
"enabled": true,
"server": "https://encrypted-proxy.example.com:8080",
"tls": {
"enabled": true,
"version": "TLSv1.3"
}
}
}
}
```
---
## 🧪 Testing & Debugging
### **Manual Tests**
```bash
# Test proxy connection
curl --proxy proxy.example.com:8080 http://httpbin.org/ip
# Test with authentication
curl --proxy user:pass@proxy.example.com:8080 http://httpbin.org/ip
# Test geolocation
curl --proxy proxy.example.com:8080 http://ipinfo.io/json
```
### **Script Debug Mode**
```powershell
$env:DEBUG_PROXY=1; npm start
```
### **Health Check Script**
```bash
#!/bin/bash
PROXY="proxy.example.com:8080"
curl --proxy $PROXY --connect-timeout 10 http://httpbin.org/status/200
echo "Proxy health: $?"
```
---
## 🛠️ Troubleshooting
| Problem | Error | Solution |
|---------|-------|----------|
| **Connection Failed** | `ECONNREFUSED` | Verify server address/port; check firewall |
| **Auth Failed** | `407 Proxy Authentication Required` | Verify username/password; check IP whitelist |
| **Timeout** | `Request timeout` | Increase timeout values; try different server |
| **SSL Error** | `certificate verify failed` | Disable SSL verification; update certificates |
### **Common Error Messages**
#### **Connection Issues**
```
[ERROR] Proxy connection failed: ECONNREFUSED
```
**Solutions:**
- ✅ Verify proxy server address and port
- ✅ Check proxy server is running
- ✅ Confirm firewall allows connections
- ✅ Test with different proxy server
#### **Authentication Issues**
```
[ERROR] Proxy authentication failed: 407 Proxy Authentication Required
```
**Solutions:**
- ✅ Verify username and password
- ✅ Check account is active with provider
- ✅ Confirm IP is whitelisted (if applicable)
- ✅ Try different authentication method
#### **Performance Issues**
```
[ERROR] Proxy timeout: Request timeout
```
**Solutions:**
- ✅ Increase timeout values
- ✅ Check proxy server performance
- ✅ Try different proxy server
- ✅ Reduce concurrent connections
---
## ⚡ Performance Optimization
### **Connection Settings**
```json
{
"browser": {
"proxy": {
"enabled": true,
"server": "proxy.example.com:8080",
"timeouts": {
"connect": 30000,
"request": 60000,
"idle": 120000
},
"connectionPooling": true,
"maxConnections": 10
}
}
}
```
### **Compression Settings**
```json
{
"browser": {
"proxy": {
"enabled": true,
"server": "proxy.example.com:8080",
"compression": true,
"gzip": true
}
}
}
```
### **Monitoring Metrics**
- **Connection Success Rate** — % of successful proxy connections
- **Response Time** — Average request latency through proxy
- **Bandwidth Usage** — Data transferred through proxy
- **Error Rate** — % of failed requests via proxy
---
## 🐳 Container Integration
### **Docker Environment**
```dockerfile
# Dockerfile
ENV PROXY_ENABLED=true
ENV PROXY_SERVER=proxy.example.com:8080
ENV PROXY_USERNAME=user
ENV PROXY_PASSWORD=pass
```
### **Kubernetes ConfigMap**
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: rewards-proxy-config
data:
proxy.json: |
{
"enabled": true,
"server": "proxy.example.com:8080",
"username": "user",
"password": "pass"
}
```
### **Environment-Specific**
```json
{
"development": {
"proxy": { "enabled": false }
},
"staging": {
"proxy": {
"enabled": true,
"server": "staging-proxy.example.com:8080"
}
},
"production": {
"proxy": {
"enabled": true,
"server": "prod-proxy.example.com:8080"
}
}
}
```
---
## 📊 Best Practices
### **Proxy Selection**
- 🏆 **Residential > Datacenter** — Better for avoiding detection
- 💰 **Paid > Free** — Reliability and security
- 🔄 **Multiple providers** — Redundancy and failover
- 🌍 **Geographic diversity** — Flexibility and compliance
### **Configuration Management**
- 🔑 **Environment variables** — Secure credential storage
- 🧪 **Test before deploy** — Verify configuration works
- 📊 **Monitor performance** — Track availability and speed
- 🔄 **Backup configs** — Ready failover options
### **Security Guidelines**
- 🔒 **HTTPS proxies** — Encrypted connections when possible
- 🛡️ **SSL verification** — Verify certificates
- 🔄 **Rotate credentials** — Regular password updates
- 👁️ **Monitor access** — Watch for unauthorized usage
---
## ⚖️ Legal & Compliance
### **Terms of Service**
- 📋 Review Microsoft's Terms of Service
- 📄 Understand proxy provider's acceptable use policy
- 🌍 Ensure compliance with local regulations
- 🗺️ Consider geographic restrictions
### **Data Privacy**
- 🔍 Understand data flow through proxy
- 📝 Review proxy provider's data retention policies
- 🔐 Implement additional encryption if needed
- 📊 Monitor proxy logs and access
### **Rate Limiting**
- ⏱️ Respect Microsoft's rate limits
- ⏸️ Implement proper delays between requests
- 🚦 Monitor for IP blocking or throttling
- 🔄 Use proxy rotation to distribute load
---
## 🔗 Related Guides
- **[Getting Started](./getting-started.md)** — Initial setup and configuration
- **[Security](./security.md)** — Privacy and data protection
- **[Docker](./docker.md)** — Container deployment with proxies
- **[Humanization](./humanization.md)** — Natural behavior patterns

648
docs/schedule.md Normal file
View File

@@ -0,0 +1,648 @@
# ⏰ Scheduler & Automation
<div align="center">
**🚀 Built-in scheduler for automated daily execution**
*Set it and forget it*
</div>
---
## 🎯 What is the Scheduler?
The built-in scheduler provides **automated script execution** at specified times without requiring external cron jobs or task schedulers.
### **Key Features**
- 📅 **Daily automation** — Run at the same time every day
- 🌍 **Timezone aware** — Handles DST automatically
- 🔄 **Multiple passes** — Execute script multiple times per run
- 🏖️ **Vacation mode** — Skip random days monthly
- 🎲 **Jitter support** — Randomize execution times
- ⚡ **Immediate start** — Option to run on startup
---
## ⚙️ Configuration
### **Basic Setup**
```json
{
"schedule": {
"enabled": true,
"time": "09:00",
"timeZone": "America/New_York",
"runImmediatelyOnStart": true
},
"passesPerRun": 2
}
```
### **Advanced Setup with Vacation Mode**
```json
{
"schedule": {
"enabled": true,
"time": "10:00",
"timeZone": "Europe/Paris",
"runImmediatelyOnStart": false
},
"passesPerRun": 3,
"vacation": {
"enabled": true,
"minDays": 3,
"maxDays": 5
}
}
```
### **Configuration Options**
| Setting | Default | Description |
|---------|---------|-------------|
| `enabled` | `false` | Enable built-in scheduler |
| `time` | `"09:00"` | Daily execution time (24-hour format) |
| `timeZone` | `"UTC"` | IANA timezone identifier |
| `runImmediatelyOnStart` | `true` | Execute once on process startup |
| `passesPerRun` | `1` | Number of complete runs per execution |
| `vacation.enabled` | `false` | Skip random monthly off-block |
| `vacation.minDays` | `3` | Minimum vacation days |
| `vacation.maxDays` | `5` | Maximum vacation days |
---
## 🚀 How It Works
### **Daily Scheduling**
1. **Calculate next run** — Timezone-aware scheduling
2. **Wait until time** — Minimal resource usage
3. **Execute passes** — Run script specified number of times
4. **Schedule next day** — Automatic DST adjustment
### **Startup Behavior**
#### **Immediate Start Enabled (`true`)**
- **Before scheduled time** → Run immediately + wait for next scheduled time
- **After scheduled time** → Run immediately + wait for tomorrow's time
#### **Immediate Start Disabled (`false`)**
- **Any time** → Always wait for next scheduled time
### **Multiple Passes**
- Each pass processes **all accounts** through **all tasks**
- Useful for **maximum point collection**
- Higher passes = **more points** but **increased detection risk**
---
## 🏖️ Vacation Mode
### **Monthly Off-Blocks**
Vacation mode randomly selects a **contiguous block of days** each month to skip execution.
### **Configuration**
```json
{
"vacation": {
"enabled": true,
"minDays": 3,
"maxDays": 5
}
}
```
### **How It Works**
- **Random selection** — Different days each month
- **Contiguous block** — Skip consecutive days, not scattered
- **Independent** — Works with weekly random off-days
- **Logged** — Shows selected vacation period
### **Example Output**
```
[SCHEDULE] Selected vacation block this month: 2025-01-15 → 2025-01-18
[SCHEDULE] Skipping run - vacation mode (3 days remaining)
```
---
## 🌍 Supported Timezones
### **North America**
- `America/New_York` — Eastern Time
- `America/Chicago` — Central Time
- `America/Denver` — Mountain Time
- `America/Los_Angeles` — Pacific Time
- `America/Phoenix` — Arizona (no DST)
### **Europe**
- `Europe/London` — GMT/BST
- `Europe/Paris` — CET/CEST
- `Europe/Berlin` — CET/CEST
- `Europe/Rome` — CET/CEST
- `Europe/Moscow` — MSK
### **Asia Pacific**
- `Asia/Tokyo` — JST
- `Asia/Shanghai` — CST
- `Asia/Kolkata` — IST
- `Australia/Sydney` — AEST/AEDT
- `Pacific/Auckland` — NZST/NZDT
---
## 🎲 Randomization & Watchdog
### **Environment Variables**
```powershell
# Add random delay before first run (5-20 minutes)
$env:SCHEDULER_INITIAL_JITTER_MINUTES_MIN=5
$env:SCHEDULER_INITIAL_JITTER_MINUTES_MAX=20
# Add daily jitter to scheduled time (2-10 minutes)
$env:SCHEDULER_DAILY_JITTER_MINUTES_MIN=2
$env:SCHEDULER_DAILY_JITTER_MINUTES_MAX=10
# Kill stuck passes after N minutes
$env:SCHEDULER_PASS_TIMEOUT_MINUTES=180
# Run each pass in separate process (recommended)
$env:SCHEDULER_FORK_PER_PASS=true
```
### **Benefits**
- **Avoid patterns** — Prevents exact-time repetition
- **Protection** — Kills stuck processes
- **Isolation** — Process separation for stability
---
## 🖥️ Running the Scheduler
### **Development Mode**
```powershell
npm run ts-schedule
```
### **Production Mode**
```powershell
npm run build
npm run start:schedule
```
### **Background Execution**
```powershell
# Windows Background (PowerShell)
Start-Process -NoNewWindow -FilePath "npm" -ArgumentList "run", "start:schedule"
# Alternative: Windows Task Scheduler (recommended)
# Create scheduled task via GUI or schtasks command
```
---
## 📊 Usage Examples
### **Basic Daily Automation**
```json
{
"schedule": {
"enabled": true,
"time": "08:00",
"timeZone": "America/New_York"
}
}
```
⏰ **Perfect for morning routine** — Catch daily resets
### **Multiple Daily Passes**
```json
{
"schedule": {
"enabled": true,
"time": "10:00",
"timeZone": "Europe/London",
"runImmediatelyOnStart": false
},
"passesPerRun": 3
}
```
🔄 **Maximum points** with higher detection risk
### **Conservative with Vacation**
```json
{
"schedule": {
"enabled": true,
"time": "20:00",
"timeZone": "America/Los_Angeles"
},
"passesPerRun": 1,
"vacation": {
"enabled": true,
"minDays": 4,
"maxDays": 6
}
}
```
🏖️ **Natural patterns** with monthly breaks
---
## 🐳 Docker Integration
### **Built-in Scheduler (Recommended)**
```yaml
services:
microsoft-rewards-script:
build: .
environment:
TZ: Europe/Paris
command: ["npm", "run", "start:schedule"]
```
- Uses `passesPerRun` from config
- Single long-running process
- No external cron needed
### **External Cron (Project Default)**
```yaml
services:
microsoft-rewards-script:
build: .
environment:
CRON_SCHEDULE: "0 7,16,20 * * *"
RUN_ON_START: "true"
```
- Uses `run_daily.sh` with random delays
- Multiple cron executions
- Lockfile prevents overlaps
---
## 📋 Logging Output
### **Scheduler Initialization**
```
[SCHEDULE] Scheduler initialized for daily 09:00 America/New_York
[SCHEDULE] Next run scheduled for 2025-01-21 09:00:00 EST
```
### **Daily Execution**
```
[SCHEDULE] Starting scheduled run (pass 1 of 2)
[SCHEDULE] Completed scheduled run in 12m 34s
[SCHEDULE] Next run scheduled for 2025-01-22 09:00:00 EST
```
### **Time Calculations**
```
[SCHEDULE] Current time: 2025-01-20 15:30:00 EDT
[SCHEDULE] Target time: 2025-01-21 09:00:00 EDT
[SCHEDULE] Waiting 17h 30m until next run
```
---
## 🛠️ Troubleshooting
| Problem | Solution |
|---------|----------|
| **Scheduler not running** | Check `enabled: true`; verify timezone format |
| **Wrong execution time** | Verify system clock; check DST effects |
| **Memory growth** | Restart process weekly; monitor logs |
| **Missed executions** | Check system sleep/hibernation; verify process |
### **Debug Commands**
```powershell
# Test timezone calculation
node -e "console.log(new Date().toLocaleString('en-US', {timeZone: 'America/New_York'}))"
# Verify config syntax
node -e "console.log(JSON.parse((Get-Content 'src/config.json' | Out-String)))"
# Check running processes
Get-Process | Where-Object {$_.ProcessName -eq "node"}
```
---
## ⚡ Performance & Best Practices
### **Optimal Timing**
- **🌅 Morning (7-10 AM)** — Catch daily resets
- **🌆 Evening (7-10 PM)** — Complete remaining tasks
- **❌ Avoid peak hours** — Reduce detection during high traffic
### **Pass Recommendations**
- **1 pass** — Safest, good for most users
- **2-3 passes** — Balance of points vs. risk
- **4+ passes** — Higher risk, development only
### **Monitoring**
- ✅ Check logs regularly for errors
- ✅ Monitor point collection trends
- ✅ Verify scheduler status weekly
---
## 🔗 Alternative Solutions
### **Windows Task Scheduler**
```powershell
# Create scheduled task
schtasks /create /tn "MS-Rewards" /tr "npm start" /sc daily /st 09:00 /sd 01/01/2025
```
### **PowerShell Scheduled Job**
```powershell
# Register scheduled job
Register-ScheduledJob -Name "MSRewards" -ScriptBlock {cd "C:\path\to\project"; npm start} -Trigger (New-JobTrigger -Daily -At 9am)
```
---
## 🔗 Related Guides
- **[Getting Started](./getting-started.md)** — Initial setup and configuration
- **[Humanization](./humanization.md)** — Natural behavior patterns
- **[Docker](./docker.md)** — Container deployment
- **[Job State](./jobstate.md)** — Execution state management
## Usage Examples
### Basic Daily Run
```json
{
"schedule": {
"enabled": true,
"time": "08:00",
"timeZone": "America/New_York"
}
}
```
### Multiple Daily Passes
```json
{
"schedule": {
"enabled": true,
"time": "10:00",
"timeZone": "Europe/London",
"runImmediatelyOnStart": false
},
"passesPerRun": 3
}
```
### Development Testing
```json
{
"schedule": {
"enabled": true,
"time": "00:01",
"timeZone": "UTC",
"runImmediatelyOnStart": true
}
}
```
## Supported Timezones
Common IANA timezone identifiers:
### North America
- `America/New_York` (Eastern Time)
- `America/Chicago` (Central Time)
- `America/Denver` (Mountain Time)
- `America/Los_Angeles` (Pacific Time)
- `America/Phoenix` (Arizona - no DST)
### Europe
- `Europe/London` (GMT/BST)
- `Europe/Paris` (CET/CEST)
- `Europe/Berlin` (CET/CEST)
- `Europe/Rome` (CET/CEST)
- `Europe/Moscow` (MSK)
### Asia Pacific
- `Asia/Tokyo` (JST)
- `Asia/Shanghai` (CST)
- `Asia/Kolkata` (IST)
- `Australia/Sydney` (AEST/AEDT)
- `Pacific/Auckland` (NZST/NZDT)
### UTC Variants
- `UTC` (Coordinated Universal Time)
- `GMT` (Greenwich Mean Time)
## Running the Scheduler
### Development Mode
```bash
npm run ts-schedule
```
### Production Mode
```bash
npm run build
npm run start:schedule
```
### Optional Randomization and Watchdog
You can introduce slight randomness to the start times and protect against stuck runs:
- `SCHEDULER_INITIAL_JITTER_MINUTES_MIN` / `SCHEDULER_INITIAL_JITTER_MINUTES_MAX`
- Adds a one‑time random delay before the very first run after the scheduler starts.
- Example: `SCHEDULER_INITIAL_JITTER_MINUTES_MIN=5` and `SCHEDULER_INITIAL_JITTER_MINUTES_MAX=20` delays the first run by 5–20 minutes.
- `SCHEDULER_DAILY_JITTER_MINUTES_MIN` / `SCHEDULER_DAILY_JITTER_MINUTES_MAX`
- Adds an extra random delay to each daily scheduled execution.
- Example: 2–10 minutes of daily jitter to avoid exact same second each day.
- `SCHEDULER_PASS_TIMEOUT_MINUTES`
- Kills a stuck pass after N minutes (default 180). Useful if the underlying browser gets stuck.
- `SCHEDULER_FORK_PER_PASS`
- Defaults to `true`. When `true`, each pass runs in a child Node process so a stuck pass can be terminated without killing the scheduler. Set to `false` to run passes in‑process (not recommended).
### Background Execution
```bash
# Linux/macOS (background process)
nohup npm run start:schedule > schedule.log 2>&1 &
# Windows (background service - requires additional setup)
# Recommend using Task Scheduler or Windows Service wrapper
```
## Process Management
### Long-Running Process
- Scheduler runs continuously
- Automatically handles timezone changes
- Graceful handling of system clock adjustments
### Memory Management
- Minimal memory footprint between runs
- Garbage collection after each execution
- No memory leaks in long-running processes
### Error Recovery
- Failed runs don't affect future scheduling
- Automatic retry on next scheduled time
- Error logging for troubleshooting
## Logging Output
### Scheduler Events
```
[SCHEDULE] Scheduler initialized for daily 09:00 America/New_York
[SCHEDULE] Next run scheduled for 2025-09-21 09:00:00 EST
[SCHEDULE] Starting scheduled run (pass 1 of 2)
[SCHEDULE] Completed scheduled run in 12m 34s
[SCHEDULE] Next run scheduled for 2025-09-22 09:00:00 EST
```
### Time Calculations
```
[SCHEDULE] Current time: 2025-09-20 15:30:00 EDT
[SCHEDULE] Target time: 2025-09-21 09:00:00 EDT
[SCHEDULE] Waiting 17h 30m until next run
```
## Integration with Other Features
### Docker Compatibility
- Scheduler works in Docker containers
- Alternative to external cron jobs
- Timezone handling in containerized environments
### Buy Mode Exclusion
- Scheduler only runs automation mode
- Buy mode (`-buy`) ignores scheduler settings
- Manual executions bypass scheduler
### Clustering
- Scheduler runs only in single-process mode
- Clustering disabled when scheduler is active
- Use scheduler OR clustering, not both
## Best Practices
### Optimal Timing
- **Morning runs**: Catch daily resets and new activities
- **Evening runs**: Complete remaining tasks before midnight
- **Avoid peak hours**: Reduce detection risk during high traffic
### Timezone Selection
- Use your local timezone for easier monitoring
- Consider Microsoft Rewards server timezone
- Account for daylight saving time changes
### Multiple Passes
- **2-3 passes**: Good balance of points vs. detection risk
- **More passes**: Higher detection risk
- **Single pass**: Safest but may miss some points
### Monitoring
- Check logs regularly for errors
- Monitor point collection trends
- Verify scheduler is running as expected
## Troubleshooting
### Common Issues
**Scheduler not running:**
- Check `enabled: true` in config
- Verify timezone format is correct
- Ensure no syntax errors in config.json
**Wrong execution time:**
- Verify system clock is accurate
- Check timezone identifier spelling
- Consider daylight saving time effects
**Memory growth over time:**
- Restart scheduler process weekly
- Monitor system resource usage
- Check for memory leaks in logs
**Missed executions:**
- System was sleeping/hibernating
- Process was killed or crashed
- Clock was adjusted significantly
### Debug Commands
```bash
# Test timezone calculation
node -e "console.log(new Date().toLocaleString('en-US', {timeZone: 'America/New_York'}))"
# Verify config syntax
node -e "console.log(JSON.parse(require('fs').readFileSync('src/config.json')))"
# Check process status
ps aux | grep "start:schedule"
```
## Alternative Solutions
### External Cron (Linux/macOS)
```bash
# Crontab entry for 9 AM daily
0 9 * * * cd /path/to/MSN-V2 && npm start
# Multiple times per day
0 9,15,21 * * * cd /path/to/MSN-V2 && npm start
```
### Windows Task Scheduler
- Create scheduled task via Task Scheduler
- Set trigger for daily execution
- Configure action to run `npm start` in project directory
### Docker Cron
```dockerfile
# Add to Dockerfile
RUN apt-get update && apt-get install -y cron
COPY crontab /etc/cron.d/rewards-cron
RUN crontab /etc/cron.d/rewards-cron
```
### Docker + Built-in Scheduler
Au lieu d'utiliser cron, vous pouvez lancer le scheduler intégré dans le conteneur (un seul process long‑vivant) :
```yaml
services:
microsoft-rewards-script:
build: .
environment:
TZ: Europe/Paris
command: ["npm", "run", "start:schedule"]
```
Dans ce mode :
- `passesPerRun` fonctionne (exécutera plusieurs passes à chaque horaire interne défini par `src/config.json`).
- Vous n'avez plus besoin de `CRON_SCHEDULE` ni de `run_daily.sh`.
### Docker + External Cron (par défaut du projet)
Si vous préférez la planification par cron système dans le conteneur (valeur par défaut du projet) :
- Utilisez `CRON_SCHEDULE` (ex.: `0 7,16,20 * * *`).
- `run_daily.sh` introduit un délai aléatoire (par défaut 5–50 min) et un lockfile pour éviter les chevauchements.
- `RUN_ON_START=true` déclenche une exécution immédiate au démarrage du conteneur (sans délai aléatoire).
## Performance Considerations
### System Resources
- Minimal CPU usage between runs
- Low memory footprint when idle
- No network activity during waiting periods
### Startup Time
- Fast initialization (< 1 second)
- Quick timezone calculations
- Immediate scheduling of next run
### Reliability
- Robust error handling
- Automatic recovery from failures
- Consistent execution timing

296
docs/security.md Normal file
View File

@@ -0,0 +1,296 @@
# 🔒 Security & Privacy Guide
<div align="center">
**🛡️ Comprehensive security measures and incident response**
*Protect your accounts and maintain privacy*
</div>
---
## 🎯 Security Overview
This guide explains how the script **detects security-related issues**, what it does automatically, and how you can **resolve incidents** safely.
### **Security Features**
- 🚨 **Automated detection** — Recognizes account compromise attempts
- 🛑 **Emergency halting** — Stops all automation during incidents
- 🔔 **Strong alerts** — Immediate notifications via Discord/NTFY
- 📋 **Recovery guidance** — Step-by-step incident resolution
- 🔒 **Privacy protection** — Local-only operation by default
---
## 🚨 Security Incidents & Resolutions
### **Recovery Email Mismatch**
#### **Symptoms**
During Microsoft login, the page shows a masked recovery email like `ko*****@hacker.net` that **doesn't match** your expected recovery email pattern.
#### **What the Script Does**
- 🛑 **Halts automation** for the current account (leaves page open for manual action)
- 🚨 **Sends strong alerts** to all channels and engages global standby
- ⏸️ **Stops processing** — No further accounts are processed
- 🔔 **Repeats reminders** every 5 minutes until intervention
#### **Likely Causes**
- ⚠️ **Account takeover** — Recovery email changed by someone else
- 🔄 **Recent change** — You changed recovery email but forgot to update config
#### **How to Fix**
1. **🔍 Verify account security** in Microsoft Account settings
2. **📝 Update config** if you changed recovery email yourself:
```json
{
"email": "your@email.com",
"recoveryEmail": "ko*****@hacker.net"
}
```
3. **🔐 Change password** and review sign-in activity if compromise suspected
4. **🚀 Restart script** to resume normal operation
#### **Prevention**
- ✅ Keep `recoveryEmail` in `accounts.json` up to date
- ✅ Use strong unique passwords and MFA
- ✅ Regular security reviews
---
### **"We Can't Sign You In" (Blocked)**
#### **Symptoms**
Microsoft presents a page titled **"We can't sign you in"** during login attempts.
#### **What the Script Does**
- 🛑 **Stops automation** and leaves page open for manual recovery
- 🚨 **Sends strong alert** with high priority notifications
- ⏸️ **Engages global standby** to avoid processing other accounts
#### **Likely Causes**
- ⏱️ **Temporary lock** — Rate limiting or security check from Microsoft
- 🚫 **Account restrictions** — Ban related to unusual activity
- 🔒 **Verification required** — SMS code, authenticator, or other challenges
#### **How to Fix**
1. **✅ Complete verification** challenges (SMS, authenticator, etc.)
2. **⏸️ Pause activity** for 24-48h if blocked repeatedly
3. **🔧 Reduce concurrency** and increase delays between actions
4. **🌐 Check proxies** — Ensure consistent IP/country
5. **📞 Appeal if needed** — Contact Microsoft if ban is suspected
#### **Prevention**
- ✅ **Respect rate limits** — Use humanization settings
- ✅ **Avoid patterns** — Don't run too many accounts from same IP
- ✅ **Geographic consistency** — Use proxies from your actual region
- ✅ **Human-like timing** — Avoid frequent credential retries
---
## 🔐 Privacy & Data Protection
### **Local-First Architecture**
- 💾 **All data local** — Credentials, sessions, logs stored locally only
- 🚫 **No telemetry** — Zero data collection or external reporting
- 🔒 **No cloud storage** — Everything remains on your machine
### **Credential Security**
```json
{
"accounts": [
{
"email": "user@example.com",
"password": "secure-password-here",
"totpSecret": "optional-2fa-secret"
}
]
}
```
**Best Practices:**
- 🔐 **Strong passwords** — Unique, complex passwords per account
- 🔑 **2FA enabled** — Time-based one-time passwords when possible
- 📁 **File permissions** — Restrict access to `accounts.json`
- 🔄 **Regular rotation** — Change passwords periodically
### **Session Management**
- 🍪 **Persistent cookies** — Stored locally in `sessions/` directory
- 🔒 **Encrypted storage** — Session data protected at rest
- ⏰ **Automatic expiry** — Old sessions cleaned up automatically
- 🗂️ **Per-account isolation** — No session data mixing
---
## 🌐 Network Security
### **Proxy Configuration**
```json
{
"browser": {
"proxy": {
"enabled": true,
"server": "proxy.example.com:8080",
"username": "user",
"password": "pass"
}
}
}
```
**Security Benefits:**
- 🎭 **IP masking** — Hide your real IP address
- 🌍 **Geographic flexibility** — Appear from different locations
- 🔒 **Traffic encryption** — HTTPS proxy connections
- 🛡️ **Detection avoidance** — Rotate IPs to avoid patterns
### **Traffic Analysis Protection**
- 🔐 **HTTPS only** — All Microsoft communications encrypted
- 🚫 **No plaintext passwords** — Credentials protected in transit
- 🛡️ **Certificate validation** — SSL/TLS verification enabled
- 🔍 **Deep packet inspection** resistant
---
## 🛡️ Anti-Detection Measures
### **Humanization**
```json
{
"humanization": {
"enabled": true,
"actionDelay": { "min": 150, "max": 450 },
"gestureMoveProb": 0.4,
"gestureScrollProb": 0.2
}
}
```
**Natural Behavior Simulation:**
- ⏱️ **Random delays** — Variable timing between actions
- 🖱️ **Mouse movements** — Subtle cursor adjustments
- 📜 **Scrolling gestures** — Natural page interactions
- 🎲 **Randomized patterns** — Avoid predictable automation
### **Browser Fingerprinting**
- 🌐 **Real user agents** — Authentic browser identification
- 📱 **Platform consistency** — Mobile/desktop specific headers
- 🔧 **Plugin simulation** — Realistic browser capabilities
- 🖥️ **Screen resolution** — Appropriate viewport dimensions
---
## 📊 Monitoring & Alerting
### **Real-Time Monitoring**
```json
{
"notifications": {
"webhook": {
"enabled": true,
"url": "https://discord.com/api/webhooks/..."
},
"ntfy": {
"enabled": true,
"url": "https://ntfy.sh",
"topic": "rewards-security"
}
}
}
```
**Alert Types:**
- 🚨 **Security incidents** — Account compromise attempts
- ⚠️ **Login failures** — Authentication issues
- 🔒 **Account blocks** — Access restrictions detected
- 📊 **Performance anomalies** — Unusual execution patterns
### **Log Analysis**
- 📝 **Detailed logging** — All actions recorded locally
- 🔍 **Error tracking** — Failed operations highlighted
- 📊 **Performance metrics** — Timing and success rates
- 🛡️ **Security events** — Incident timeline reconstruction
---
## 🧪 Security Testing
### **Penetration Testing**
```powershell
# Test credential handling
$env:DEBUG_SECURITY=1; npm start
# Test session persistence
$env:DEBUG_SESSIONS=1; npm start
# Test proxy configuration
$env:DEBUG_PROXY=1; npm start
```
### **Vulnerability Assessment**
- 🔍 **Regular audits** — Check for security issues
- 📦 **Dependency scanning** — Monitor npm packages
- 🔒 **Code review** — Manual security analysis
- 🛡️ **Threat modeling** — Identify attack vectors
---
## 📋 Security Checklist
### **Initial Setup**
- ✅ **Strong passwords** for all accounts
- ✅ **2FA enabled** where possible
- ✅ **File permissions** restricted to user only
- ✅ **Proxy configured** if desired
- ✅ **Notifications set up** for alerts
### **Regular Maintenance**
- ✅ **Password rotation** every 90 days
- ✅ **Session cleanup** weekly
- ✅ **Log review** for anomalies
- ✅ **Security updates** for dependencies
- ✅ **Backup verification** of configurations
### **Incident Response**
- ✅ **Alert investigation** within 15 minutes
- ✅ **Account verification** when suspicious
- ✅ **Password changes** if compromise suspected
- ✅ **Activity review** in Microsoft account settings
- ✅ **Documentation** of incidents and resolutions
---
## 🚨 Emergency Procedures
### **Account Compromise Response**
1. **🛑 Immediate shutdown** — Stop all script activity
2. **🔒 Change passwords** — Update all affected accounts
3. **📞 Contact Microsoft** — Report unauthorized access
4. **🔍 Audit activity** — Review recent sign-ins and changes
5. **🛡️ Enable additional security** — Add 2FA, recovery options
6. **📋 Document incident** — Record timeline and actions taken
### **Detection Evasion**
1. **⏸️ Temporary suspension** — Pause automation for 24-48h
2. **🔧 Reduce intensity** — Lower pass counts and frequencies
3. **🌐 Change IPs** — Rotate proxies or VPN endpoints
4. **⏰ Adjust timing** — Modify scheduling patterns
5. **🎭 Increase humanization** — More natural behavior simulation
---
## 🔗 Quick Reference Links
When the script detects a security incident, it opens this guide directly to the relevant section:
- **[Recovery Email Mismatch](#recovery-email-mismatch)** — Email change detection
- **[Account Blocked](#we-cant-sign-you-in-blocked)** — Login restriction handling
---
## 🔗 Related Guides
- **[Getting Started](./getting-started.md)** — Initial setup and configuration
- **[Accounts & 2FA](./accounts.md)** — Microsoft account setup
- **[Proxy Configuration](./proxy.md)** — Network privacy and routing
- **[Humanization](./humanization.md)** — Natural behavior patterns

395
docs/update.md Normal file
View File

@@ -0,0 +1,395 @@
# 🔄 Auto-Update System
<div align="center">
**🚀 Automatic updates to keep your installation current**
*Set it and forget it*
</div>
---
## 🎯 What is Auto-Update?
The automatic update system runs **after script completion** to keep your installation current with the latest features, bug fixes, and security patches.
### **Key Features**
- 🔄 **Automatic updates** — Runs after each script completion
- 🛡️ **Safe by design** — Fast-forward only Git updates
- 🐳 **Docker support** — Container image updates
- 🛠️ **Custom scripts** — Extensible update process
- 🔒 **Error resilient** — Failed updates don't break main script
---
## ⚙️ Configuration
### **Basic Setup**
```json
{
"update": {
"git": true,
"docker": false,
"scriptPath": "setup/update/update.mjs"
}
}
```
### **Configuration Options**
| Setting | Description | Default |
|---------|-------------|---------|
| `git` | Enable Git-based updates | `true` |
| `docker` | Enable Docker container updates | `false` |
| `scriptPath` | Path to custom update script | `"setup/update/update.mjs"` |
---
## 🚀 Update Methods
### **Git Updates (`git: true`)**
#### **What It Does**
- 📥 **Fetches latest changes** from remote repository
- ⚡ **Fast-forward only pulls** (safe updates)
- 📦 **Reinstalls dependencies** (`npm ci`)
- 🔨 **Rebuilds the project** (`npm run build`)
#### **Requirements**
- ✅ Git installed and available in PATH
- ✅ Repository is a Git clone (not downloaded ZIP)
- ✅ No uncommitted local changes
- ✅ Internet connectivity
#### **Process**
```bash
git fetch --all --prune
git pull --ff-only
npm ci
npm run build
```
### **Docker Updates (`docker: true`)**
#### **What It Does**
- 📥 **Pulls latest container images**
- 🔄 **Restarts services** with new images
- 💾 **Preserves configurations** and mounted volumes
#### **Requirements**
- ✅ Docker and Docker Compose installed
- ✅ `docker-compose.yml` file present
- ✅ Proper container registry access
#### **Process**
```bash
docker compose pull
docker compose up -d
```
---
## 🛠️ Custom Update Scripts
### **Default Script**
- **Path** — `setup/update/update.mjs`
- **Format** — ES modules
- **Arguments** — Command line flags
### **Script Arguments**
- `--git` — Enable Git update process
- `--docker` — Enable Docker update process
- Both flags can be combined
### **Custom Script Example**
```javascript
// custom-update.mjs
import { execSync } from 'child_process'
const args = process.argv.slice(2)
if (args.includes('--git')) {
console.log('🔄 Running custom Git update...')
execSync('git pull && npm install', { stdio: 'inherit' })
}
if (args.includes('--docker')) {
console.log('🐳 Running custom Docker update...')
execSync('docker-compose pull && docker-compose up -d', { stdio: 'inherit' })
}
```
---
## ⏰ Execution Timing
### **When Updates Run**
| Scenario | Update Runs |
|----------|-------------|
| **Normal completion** | ✅ All accounts processed successfully |
| **Error completion** | ✅ Script finished with errors but completed |
| **Interruption** | ❌ Script killed or crashed mid-execution |
### **Update Sequence**
1. **🏁 Main script completion** — All accounts processed
2. **📊 Conclusion webhook** sent (if enabled)
3. **🚀 Update process begins**
4. **📥 Git updates** (if enabled)
5. **🐳 Docker updates** (if enabled)
6. **🔚 Process exits**
---
## 🛡️ Safety Features
### **Git Safety**
- ⚡ **Fast-forward only** — Prevents overwriting local changes
- 📦 **Dependency verification** — Ensures `npm ci` succeeds
- 🔨 **Build validation** — Confirms TypeScript compilation works
### **Error Handling**
- ✅ **Update failures** don't break main script
- 🔇 **Silent failures** — Errors logged but don't crash process
- 🔄 **Rollback protection** — Failed updates don't affect current installation
### **Concurrent Execution**
- 🔒 **Single update process** — Multiple instances don't conflict
- 🚫 **Lock-free design** — No file locking needed
- 🎯 **Independent updates** — Each script copy updates separately
---
## 📊 Monitoring Updates
### **Log Output**
```
[UPDATE] Starting post-run update process
[UPDATE] Git update enabled, Docker update disabled
[UPDATE] Running: git fetch --all --prune
[UPDATE] Running: git pull --ff-only
[UPDATE] Running: npm ci
[UPDATE] Running: npm run build
[UPDATE] Update completed successfully
```
### **Update Verification**
```powershell
# Check if updates are pending
git status
# View recent commits
git log --oneline -5
# Verify build status
npm run build
```
---
## 📋 Use Cases
### **Development Environment**
| Benefit | Description |
|---------|-------------|
| **Synchronized** | Keep local installation current with repository |
| **Automated** | Automatic dependency updates |
| **Seamless** | Integration of bug fixes and features |
### **Production Deployment**
| Benefit | Description |
|---------|-------------|
| **Security** | Automated security patches |
| **Features** | Updates without manual intervention |
| **Consistent** | Same update process across servers |
### **Docker Environments**
| Benefit | Description |
|---------|-------------|
| **Images** | Container image updates |
| **Security** | Patches in base images |
| **Automated** | Service restarts |
---
## 📋 Best Practices
### **Git Configuration**
- 🧹 **Clean working directory** — Commit or stash local changes
- 🌿 **Stable branch** — Use `main` or `stable` for auto-updates
- 📝 **Regular commits** — Keep repository history clean
- 💾 **Backup data** — Sessions and accounts before updates
### **Docker Configuration**
- 🏷️ **Image tagging** — Use specific tags, not `latest` for production
- 💾 **Volume persistence** — Ensure data volumes are mounted
- 🔗 **Service dependencies** — Configure proper startup order
- 🎯 **Resource limits** — Set appropriate memory and CPU limits
### **Monitoring**
- 📝 **Check logs regularly** — Monitor update success/failure
- 🧪 **Test after updates** — Verify script functionality
- 💾 **Backup configurations** — Preserve working setups
- 📊 **Version tracking** — Record successful versions
---
## 🛠️ Troubleshooting
### **Git Issues**
| Error | Solution |
|-------|----------|
| **"Not a git repository"** | Clone repository instead of downloading ZIP |
| **"Local changes would be overwritten"** | Commit or stash local changes |
| **"Fast-forward not possible"** | Repository diverged - reset to remote state |
#### **Git Reset Command**
```powershell
# Reset to remote state (⚠️ loses local changes)
git fetch origin
git reset --hard origin/main
```
### **Docker Issues**
| Error | Solution |
|-------|----------|
| **"Docker not found"** | Install Docker and Docker Compose |
| **"Permission denied"** | Add user to docker group |
| **"No docker-compose.yml"** | Create compose file or use custom script |
#### **Docker Permission Fix**
```powershell
# Windows: Ensure Docker Desktop is running
# Linux: Add user to docker group
sudo usermod -aG docker $USER
```
### **Network Issues**
| Error | Solution |
|-------|----------|
| **"Could not resolve host"** | Check internet connectivity |
| **"Connection timeout"** | Check firewall and proxy settings |
---
## 🔧 Manual Updates
### **Git Manual Update**
```powershell
git fetch --all --prune
git pull --ff-only
npm ci
npm run build
```
### **Docker Manual Update**
```powershell
docker compose pull
docker compose up -d
```
### **Dependencies Only**
```powershell
npm ci
npm run build
```
---
## ⚙️ Update Configuration
### **Complete Disable**
```json
{
"update": {
"git": false,
"docker": false
}
}
```
### **Selective Enable**
```json
{
"update": {
"git": true, // Keep Git updates
"docker": false // Disable Docker updates
}
}
```
### **Custom Script Path**
```json
{
"update": {
"git": true,
"docker": false,
"scriptPath": "my-custom-update.mjs"
}
}
```
---
## 🔒 Security Considerations
### **Git Security**
- ✅ **Trusted remote** — Updates pull from configured remote only
- ⚡ **Fast-forward only** — Prevents malicious rewrites
- 📦 **NPM registry** — Dependencies from official registry
### **Docker Security**
- 🏷️ **Verified images** — Container images from configured registries
- ✍️ **Image signatures** — Verify when possible
- 🔍 **Security scanning** — Regular scanning of base images
### **Script Execution**
- 👤 **Same permissions** — Update scripts run with same privileges
- 🚫 **No escalation** — No privilege escalation during updates
- 🔍 **Review scripts** — Custom scripts should be security reviewed
---
## 🎯 Environment Examples
### **Development**
```json
{
"update": {
"git": true,
"docker": false
}
}
```
### **Production**
```json
{
"update": {
"git": false,
"docker": true
}
}
```
### **Hybrid**
```json
{
"update": {
"git": true,
"docker": true,
"scriptPath": "setup/update/production-update.mjs"
}
}
```
---
## 🔗 Related Guides
- **[Getting Started](./getting-started.md)** — Initial setup and configuration
- **[Docker](./docker.md)** — Container deployment and management
- **[Scheduler](./schedule.md)** — Automated timing and execution
- **[Security](./security.md)** — Privacy and data protection