cruter 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +571 -0
  2. package/bin/index.js +2 -0
  3. package/package.json +32 -0
package/README.md ADDED
@@ -0,0 +1,571 @@
1
+ # Cruter
2
+
3
+ Microsoft Office 365 email validator and categorizer. Validate bulk email lists, categorize account types, and track results — all from the command line.
4
+
5
+ **Proxy Support** | **Concurrent Processing** | **Real-time Categorization**
6
+
7
+ ---
8
+
9
+ ## What is Cruter?
10
+
11
+ Cruter validates and categorizes Microsoft Office 365 email accounts. It identifies whether an email exists and determines its account type in real-time.
12
+
13
+ ### Categories
14
+
15
+ | Category | Description |
16
+ |---|---|
17
+ | **Outlook** | Personal Microsoft accounts (hotmail, outlook, live, msn) |
18
+ | **Office 365** | Business and enterprise Office 365 accounts |
19
+ | **Adfs** | Active Directory Federation Services |
20
+ | **GoDaddy** | GoDaddy email hosting |
21
+ | **Okta** | Okta Single Sign-On |
22
+ | **Duo Security** | Duo Security authentication |
23
+ | **Office (Others)** | Other federated Office accounts |
24
+ | **Invalid** | Non-existent or non-Office emails |
25
+
26
+ ---
27
+
28
+ ## Features
29
+
30
+ - **No Captcha** — Direct validation, no captcha solving
31
+ - **8 Categories** — Sorts emails into detailed account types
32
+ - **Proxy Support** — SOCKS5, SOCKS4, HTTP, HTTPS with rotation and authentication
33
+ - **Concurrent Processing** — Configurable parallel validation
34
+ - **Real-time Progress** — Speed, ETA, and category breakdown while running
35
+ - **Duplicate Tracking** — Per-project tracking to skip already-checked emails
36
+ - **Device Management** — PIN protection, security questions, multi-device support
37
+ - **Rate Limiting** — Configurable request throttling
38
+ - **Graceful Shutdown** — Ctrl+C flushes pending results before exiting
39
+
40
+ ---
41
+
42
+ ## Installation
43
+
44
+ ```bash
45
+ npm install -g cruter
46
+ ```
47
+
48
+ Verify the installation:
49
+
50
+ ```bash
51
+ cruter --version
52
+ ```
53
+
54
+ ---
55
+
56
+ ## Quick Start
57
+
58
+ ### 1. Create Configuration
59
+
60
+ ```bash
61
+ cruter init
62
+ ```
63
+
64
+ Creates `config.toml` in your current directory with default settings.
65
+
66
+ ### 2. Authenticate
67
+
68
+ ```bash
69
+ cruter login <your-access-token>
70
+ ```
71
+
72
+ First time login will prompt you to:
73
+
74
+ - Create a 6-digit PIN
75
+ - Set up a security question for PIN recovery
76
+
77
+ ### 3. Prepare Email List
78
+
79
+ Create `emails.txt` with one email per line:
80
+
81
+ ```
82
+ john.doe@company.com
83
+ jane.smith@business.net
84
+ user@outlook.com
85
+ admin@domain.org
86
+ ```
87
+
88
+ ### 4. Start Validation
89
+
90
+ ```bash
91
+ cruter start
92
+ ```
93
+
94
+ Results are saved to separate files per category in your output folder.
95
+
96
+ Validate a specific amount:
97
+
98
+ ```bash
99
+ cruter start 500
100
+ ```
101
+
102
+ ---
103
+
104
+ ## Configuration
105
+
106
+ Cruter supports `config.toml` (default) and `config.jsonc` formats.
107
+
108
+ ### Basic Settings
109
+
110
+ ```toml
111
+ projectName = "my-project" # For duplicate tracking
112
+ outputFolder = "./cruter-output" # Where results are saved
113
+ filePath = "./emails.txt" # Email list to validate
114
+ allowDuplicate = false # Skip already-checked emails
115
+
116
+ concurrency = 10 # Parallel workers (5-15 recommended)
117
+ intervalCap = 1000 # Max requests per interval
118
+ interval = 1000 # Interval in milliseconds
119
+
120
+ maximumError = 5 # Consecutive errors before action
121
+ stopIfMaximumErrorReached = false # true = stop, false = continue
122
+ ```
123
+
124
+ ### Proxy Settings
125
+
126
+ ```toml
127
+ [proxy]
128
+ enabled = true
129
+ stopIfNone = true # Stop if all proxies fail
130
+ rotate = true # Rotate between proxies
131
+ maximumProxyError = 5 # Errors before disabling a proxy
132
+ stopIfMaximumProxyErrorReached = false
133
+
134
+ [[proxy.proxies]]
135
+ useMe = true
136
+ protocol = "socks5" # socks5, socks4, http, https
137
+ host = "proxy.example.com"
138
+ port = 1080
139
+ useAuth = true
140
+ username = "your-username"
141
+ password = "your-password"
142
+
143
+ # Add more proxies by duplicating the [[proxy.proxies]] block
144
+ [[proxy.proxies]]
145
+ useMe = true
146
+ protocol = "http"
147
+ host = "proxy2.example.com"
148
+ port = 8080
149
+ useAuth = false
150
+ username = ""
151
+ password = ""
152
+ ```
153
+
154
+ ### JSONC Format
155
+
156
+ Use `--jsonc` to create a JSONC config instead:
157
+
158
+ ```bash
159
+ cruter init --jsonc
160
+ ```
161
+
162
+ Convert between formats:
163
+
164
+ ```bash
165
+ cruter convert
166
+ ```
167
+
168
+ ---
169
+
170
+ ## Output
171
+
172
+ Results are organized into separate files:
173
+
174
+ ```
175
+ ./cruter-output/
176
+ ├── Outlook.txt
177
+ ├── Office 365.txt
178
+ ├── Adfs.txt
179
+ ├── GoDaddy.txt
180
+ ├── Okta.txt
181
+ ├── Duo Security.txt
182
+ ├── Office (Others).txt
183
+ └── notOfficeOrInvalid.txt
184
+ ```
185
+
186
+ Each file contains one email per line. Invalid emails include the detected provider:
187
+
188
+ ```
189
+ user@gmail.com - Google
190
+ user@yahoo.com - Yahoo
191
+ ```
192
+
193
+ ---
194
+
195
+ ## Commands
196
+
197
+ ### Core
198
+
199
+ | Command | Description |
200
+ |---|---|
201
+ | `cruter init` | Create config file |
202
+ | `cruter init --jsonc` | Create JSONC config |
203
+ | `cruter convert` | Convert config between TOML and JSONC |
204
+ | `cruter start [N]` | Start validation (optionally limit to N emails) |
205
+ | `cruter login <token>` | Authenticate with access token |
206
+ | `cruter logout` | Log out current device |
207
+
208
+ ### Configuration
209
+
210
+ Update config values without editing the file:
211
+
212
+ | Command | Description |
213
+ |---|---|
214
+ | `cruter set --output <path>` | Set output folder |
215
+ | `cruter set --emails <path>` | Set email file path |
216
+ | `cruter set --project <name>` | Set project name |
217
+ | `cruter set --concurrency <n>` | Set parallel workers |
218
+ | `cruter set --interval <ms>` | Set rate limit interval |
219
+ | `cruter set --interval-cap <n>` | Set max requests per interval |
220
+ | `cruter set --max-errors <n>` | Set error threshold |
221
+ | `cruter set --allow-duplicates` | Allow duplicate emails |
222
+ | `cruter set --no-allow-duplicates` | Filter duplicate emails |
223
+
224
+ Multiple values can be set at once:
225
+
226
+ ```bash
227
+ cruter set --project campaign-2 --output ./results --concurrency 20
228
+ ```
229
+
230
+ ### Duplicate Tracking
231
+
232
+ | Command | Description |
233
+ |---|---|
234
+ | `cruter stats` | View project statistics |
235
+ | `cruter clear --current` | Clear current project tracking |
236
+ | `cruter clear --project <name>` | Clear specific project |
237
+ | `cruter clear --force` | Skip confirmation prompt |
238
+
239
+ Combine flags:
240
+
241
+ ```bash
242
+ cruter clear -cf # Clear current project, skip prompt
243
+ cruter clear -p old-data # Clear specific project
244
+ ```
245
+
246
+ ### Device Management
247
+
248
+ | Command | Description |
249
+ |---|---|
250
+ | `cruter auth list` | List all registered devices |
251
+ | `cruter auth device <id>` | View device details (supports partial ID) |
252
+ | `cruter auth pin` | Change your PIN |
253
+ | `cruter auth reset-pin <token>` | Reset PIN via security questions |
254
+
255
+ ### Security Questions
256
+
257
+ | Command | Description |
258
+ |---|---|
259
+ | `cruter auth security-questions` | View your security questions |
260
+ | `cruter auth add-security` | Add a security question (max 3) |
261
+ | `cruter auth update-security <n>` | Update question by number (1-3) |
262
+ | `cruter auth remove-security <n>` | Remove question by number (1-3) |
263
+
264
+ ### Updates
265
+
266
+ | Command | Description |
267
+ |---|---|
268
+ | `cruter check-update` | Check for new versions |
269
+ | `cruter upgrade` | Install the latest version |
270
+
271
+ ### Help
272
+
273
+ ```bash
274
+ cruter --help # General help
275
+ cruter --version # Show version
276
+ cruter start --help # Help for a specific command
277
+ cruter auth --help # Help for auth subcommands
278
+ ```
279
+
280
+ ---
281
+
282
+ ## Progress Display
283
+
284
+ During validation:
285
+
286
+ ```
287
+ Processing |████████████░░░░░░░░| 60% | 600/1000 | 12.5/s | ETA 0:32
288
+ ✓ 480 valid | ✗ 95 invalid | ⚠ 2 errors | avg 245ms
289
+ ```
290
+
291
+ After completion:
292
+
293
+ ```
294
+ ✨ Processing Complete
295
+ ─────────────────────────────────────────────
296
+ Total: 1000 emails
297
+ Valid: 900
298
+ Invalid: 95
299
+ Errors: 5
300
+ ─────────────────────────────────────────────
301
+ Duration: 1:20
302
+ Speed: 12.5 emails/sec
303
+ Avg: 245ms/email
304
+ ```
305
+
306
+ ---
307
+
308
+ ## Device Management
309
+
310
+ ### Limits
311
+
312
+ - Maximum **3 active devices** per account
313
+ - Devices inactive for 30+ days are auto-removed
314
+ - 3-day cooling period after auto-removal
315
+
316
+ ### Logout Wait Period
317
+
318
+ After logging out, you must wait before logging back in on the same device:
319
+
320
+ - **30+ days of usage**: 3-day wait
321
+ - **Less than 30 days**: 14-day wait
322
+
323
+ ### PIN
324
+
325
+ - 6-digit PIN required for authentication
326
+ - Optional hint to help you remember
327
+ - Can be reset using security questions
328
+
329
+ ### Security Questions
330
+
331
+ - 1-3 questions for PIN recovery
332
+ - Choose from predefined questions or write your own
333
+ - Required to reset a forgotten PIN
334
+
335
+ ---
336
+
337
+ ## Proxies
338
+
339
+ ### Why Use Proxies?
340
+
341
+ - Avoid rate limiting from a single IP
342
+ - Distribute requests across multiple IPs
343
+ - Increase validation throughput
344
+
345
+ ### Setup
346
+
347
+ ```toml
348
+ [proxy]
349
+ enabled = true
350
+ rotate = true
351
+
352
+ [[proxy.proxies]]
353
+ useMe = true
354
+ protocol = "socks5"
355
+ host = "proxy.example.com"
356
+ port = 1080
357
+ useAuth = true
358
+ username = "user"
359
+ password = "pass"
360
+ ```
361
+
362
+ Cruter automatically:
363
+
364
+ - Rotates between available proxies
365
+ - Disables proxies that exceed the error threshold
366
+ - Retries failed requests with a different proxy
367
+ - Falls back to direct connection if all proxies fail (unless `stopIfNone = true`)
368
+
369
+ ### Supported Protocols
370
+
371
+ - `socks5`
372
+ - `socks4`
373
+ - `http`
374
+ - `https`
375
+
376
+ ---
377
+
378
+ ## Rate Limiting
379
+
380
+ Control request rate to stay under detection thresholds:
381
+
382
+ ```toml
383
+ concurrency = 10 # 10 simultaneous checks
384
+ intervalCap = 100 # Max 100 requests...
385
+ interval = 1000 # ...per 1000ms (1 second)
386
+ ```
387
+
388
+ **Example**: 10 concurrent workers, max 100 requests per second.
389
+
390
+ ---
391
+
392
+ ## Duplicate Tracking
393
+
394
+ Cruter tracks checked emails per project to avoid rechecking:
395
+
396
+ ```bash
397
+ cruter stats # View current project stats
398
+ cruter clear --current # Clear and re-check
399
+ cruter clear --project old-run # Clear a different project
400
+ ```
401
+
402
+ Benefits:
403
+
404
+ - Resume interrupted validation — already-checked emails are skipped
405
+ - Track validation history per project
406
+ - Switch between projects with different `projectName` values
407
+
408
+ ---
409
+
410
+ ## Best Practices
411
+
412
+ ### Performance
413
+
414
+ 1. Start with concurrency of 5, increase to 10-20 if stable
415
+ 2. Use `intervalCap` of 50-200 per second
416
+ 3. Use 3-10 proxies for best results, or one rotating proxy
417
+ 4. Test with 100 emails first, then scale up
418
+
419
+ ### Reliability
420
+
421
+ 1. Enable duplicate tracking (`allowDuplicate = false`)
422
+ 2. Use proxies to avoid IP-based rate limits
423
+ 3. If error rate exceeds 10%, reduce concurrency and increase interval
424
+ 4. Monitor the error count in the progress display
425
+
426
+ ### Security
427
+
428
+ 1. Never share your access token
429
+ 2. Set up 2-3 security questions for PIN recovery
430
+ 3. Use a non-obvious PIN
431
+ 4. Log out from devices you no longer use
432
+
433
+ ---
434
+
435
+ ## Troubleshooting
436
+
437
+ **"Not authenticated"**
438
+
439
+ ```bash
440
+ cruter login <your-token>
441
+ ```
442
+
443
+ **"Configuration file not found"**
444
+
445
+ ```bash
446
+ cruter init
447
+ ```
448
+
449
+ **"Email file not found"**
450
+
451
+ ```bash
452
+ cruter set --emails ./path/to/emails.txt
453
+ ```
454
+
455
+ **"Maximum consecutive errors reached"**
456
+
457
+ - Check your internet connection
458
+ - Verify proxy settings if enabled
459
+ - Reduce concurrency: `cruter set --concurrency 5`
460
+ - Increase interval: `cruter set --interval 2000`
461
+
462
+ **"Device limit reached"**
463
+
464
+ ```bash
465
+ cruter auth list # See all devices
466
+ cruter logout # Logout from old device
467
+ ```
468
+
469
+ **High error rate**
470
+
471
+ - Enable proxy rotation
472
+ - Reduce concurrency to 5
473
+ - Increase interval to 2000ms
474
+ - Check proxy health
475
+
476
+ **Slow validation**
477
+
478
+ - Increase concurrency to 15-20
479
+ - Use multiple fast proxies
480
+ - Reduce interval (minimum 500ms recommended)
481
+
482
+ ---
483
+
484
+ ## Updating
485
+
486
+ Check for updates:
487
+
488
+ ```bash
489
+ cruter check-update
490
+ ```
491
+
492
+ Install the latest version:
493
+
494
+ ```bash
495
+ cruter upgrade
496
+ ```
497
+
498
+ Cruter detects your package manager (npm, bun, pnpm, yarn) and runs the appropriate install command.
499
+
500
+ ---
501
+
502
+ ## Examples
503
+
504
+ ### Basic
505
+
506
+ ```bash
507
+ cruter init
508
+ cruter login ABC123TOKEN
509
+ cruter start
510
+ ```
511
+
512
+ ### Validate First 500 Emails
513
+
514
+ ```bash
515
+ cruter start 500
516
+ ```
517
+
518
+ ### High-Speed with Proxies
519
+
520
+ ```toml
521
+ concurrency = 20
522
+ intervalCap = 2000
523
+ interval = 1000
524
+
525
+ [proxy]
526
+ enabled = true
527
+ rotate = true
528
+
529
+ [[proxy.proxies]]
530
+ useMe = true
531
+ protocol = "socks5"
532
+ host = "fast-proxy-1.com"
533
+ port = 1080
534
+
535
+ [[proxy.proxies]]
536
+ useMe = true
537
+ protocol = "socks5"
538
+ host = "fast-proxy-2.com"
539
+ port = 1080
540
+ ```
541
+
542
+ ```bash
543
+ cruter start
544
+ ```
545
+
546
+ ### Resume After Interruption
547
+
548
+ ```bash
549
+ # Just run again — already-checked emails are skipped
550
+ cruter start
551
+
552
+ # Or clear tracking to start fresh
553
+ cruter clear -c
554
+ cruter start
555
+ ```
556
+
557
+ ### Change Settings on the Fly
558
+
559
+ ```bash
560
+ cruter set --concurrency 20 --interval 500
561
+ cruter set --emails new-batch.txt --project batch-2
562
+ cruter start
563
+ ```
564
+
565
+ ---
566
+
567
+ ## License
568
+
569
+ Copyright 2024 Cruter. All rights reserved.
570
+
571
+ This software is proprietary and confidential. Unauthorized copying, distribution, or use is strictly prohibited.