feat: mcaptcha/cli isntructions

config/_default/menus.toml

@@ -4,11 +4,11 @@
   identifier = "Webmasters"
   url = "/docs/webmasters/"
 
-#[[docs]]
-#  name = "Terminology"
-#  weight = 520
-#  identifier = "Terminology"
-#  url = "/docs/terminology/"
+[[docs]]
+  name = "User Manual"
+  weight = 520
+  identifier = "user-manual"
+  url = "/docs/user-manual/"
 
 [[docs]]
   name = "Self-Hosting"

content/docs/user-manual/_index.md

@@ -0,0 +1,9 @@
+---
+title : "User Manual"
+description: "Introduction to mCaptcha for users"
+lead: ""
+date: 2023-10-27T08:48:45+00:00
+lastmod: 2023-10-27T08:48:45+00:00
+draft: false
+images: []
+---

content/docs/user-manual/cli.md

@@ -0,0 +1,151 @@
+---
+title: "CLI tool"
+description: "Instructions to install mCaptcha CLI"
+lead: ""
+date: 2023-10-27T08:48:45+00:00
+lastmod: 2023-10-27T08:48:45+00:00
+draft: false
+menu:
+  docs:
+    parent: "user-manual"
+---
+
+A CLI tool exists to compute mCaptcha challenges. It can be installed
+from multiple sources:
+
+## Install
+
+### crates.io
+
+The CLI tool is available on, [crates.io](https://crates.io), the Rust
+language's package registry. Rust language toolchain is required to
+install from crates.io, please see [rustup.rs](https://rustup.rs) for
+Instructions to install it.
+
+```bash
+cargo install mcaptcha-cli
+```
+
+### Pre-compiled binaries
+
+Nightly builds and stable releases are regularly published to
+[dl.mcaptcha.org](https://dl.mcaptcha.org/mcaptcha/cli) for a variety of
+CPU architectures and operating systems.
+
+1. Download binary, checksum and GPG signature files
+
+```bash
+wget https://dl.mcaptcha.org/mcaptcha/cli/{VERSION}/{FILENAME}.tar.gz
+wget https://dl.mcaptcha.org/mcaptcha/cli/{VERSION}/{FILENAME}.tar.gz.asc
+wget https://dl.mcaptcha.org/mcaptcha/cli/{VERSION}/{FILENAME}.tar.gz.sha256
+```
+
+2. Verify checksum
+
+```bash
+sha256sum -c {FILENAME}.tar.gz.sha256
+```
+
+3. Download mCaptcha's GPG release keys and verify GPG signature
+
+```bash
+gpg --keyserver keyserver.ubuntu.com --recv 73DAC973A9ADBB9ADCB5CDC4595A08135BA9FF73
+gpg --verify {FILENAME}.tar.gz.asc
+```
+
+4. Install Binary
+
+```bash
+tar -xvzf {FILENAME}.tar.gz && sudo cp {FILENAME}/mcaptcha-cli /usr/local/bin
+```
+
+### Build from source
+
+1. Install Rust tool chain
+   Please see [here](https://rustup.rs) for instructions.
+2. Download source code
+
+```bash
+git clone https://git.batsense.net/mCaptcha/cli
+```
+
+3. Compile and install
+
+```bash
+cargo build --release && sudp cp ./target/release/mcaptcha-cli
+/usr/local/bin
+```
+
+## Pass mCaptcha challenge
+
+The CLI tool requires details about the challenge to work on it. The
+tool can be used in three different modes compute challenge:
+
+1. Protected Page: Compute mCaptcha challenge for the CAPTCHA at a
+   protected page
+2. Widget URL: Compute PoW for captcha at widget URL
+3. (Developer mode) Offline: Computes PoW over given CAPTCHA parameters
+
+### From protected page URL
+
+The most convenient mode: copy the URL of the webpage which has the
+mCaptcha widget (example: showcase.mcaptcha.org) and run the CLI tool
+with it to get an authorization code:
+Compute challenge using the URL
+
+```bash
+03:39 atm@lab cli ±|feat-parse-webpage ✗|→ mcaptcha-cli protected-page https://showcase.mcaptcha.org/
+Authorization token: eRAZJiMrW58uDYA1s64Tmwq1u30HutuF
+```
+
+### Widget URL
+
+If you have the widget URL (will be in format https://mcaptcha.example.org/widget?sitekey=randomstring), it can be used to solve challenge as well:
+
+```bash
+Compute PoW by fetching parameters from  CAPTCHA URL
+
+Usage: mcaptcha-cli online --url <URL>
+
+Options:
+  -u, --url <URL>  URL of the CAPTCHA. Example:  https://example.org/widget?sitekey=foo
+  -h, --help       Print help
+```
+
+Example usage:
+
+```bash
+13:32 atm@lab cli ±|online ✗|→ mcaptcha-cli online -u https://demo.mcaptcha.org/widget?sitekey=pHy0AktWyOKuxZDzFfoaewncWecCHo23
+Authorization token: 3xleN26OctBuVu3X4t6CYyUjErhaxQvz
+```
+
+### [Developer mode] Offline
+
+Useful while debugging mCaptcha configurations, works on raw challenge
+parameters.
+
+Help menu:
+
+```bash
+Compute PoW with offline parameters
+
+Usage: mcaptcha-cli offline --salt <SALT> --phrase <PHRASE> --difficulty-factor <DIFFICULTY_FACTOR>
+
+Options:
+  -s, --salt <SALT>                            Salt with which PoW should be computed
+  -p, --phrase <PHRASE>                        Phrase over which PoW should be computed
+  -d, --difficulty-factor <DIFFICULTY_FACTOR>  Difficulty Factor
+  -h, --help                                   Print help
+```
+
+Example usage:
+
+```bash
+13:28 atm@lab cli ±|online|→ mcaptcha-cli offline -s $(rand 32) -p $(rand 32) -d 50000
+difficulty: 50000
+nonce: 90507
+original phrase: f351f333d44b2c6b5bf7f033b065bbb8fb5e9dd153bd402e43ed04425f5a3859
+result: 340276562956196291522979356090220150471
+```
+
+Where rand is [this](https://github.com/realaravinth/dotfiles/blob/6fc6c87cc912e17488a35c0d3327ecf393221270/scripts/rand#L20) script.