diff --git a/config/_default/menus.toml b/config/_default/menus.toml index c035a2a..bd789ed 100644 --- a/config/_default/menus.toml +++ b/config/_default/menus.toml @@ -1,47 +1,61 @@ [[docs]] - name = "Prologue" - weight = 10 - identifier = "prologue" - url = "/docs/prologue/" + name = "Introduction" + weight = 510 + identifier = "Introduction" + url = "/docs/introduction/" [[docs]] - name = "Help" - weight = 60 - identifier = "help" - url = "/docs/help/" + name = "Terminology" + weight = 520 + identifier = "Terminology" + url = "/docs/terminology/" +[[docs]] + name = "Self-Hosted" + weight = 530 + identifier = "Self-Hosted" + url = "/docs/self-hosted/" [[docs]] name = "API" - weight = 50 + weight = 550 identifier = "API" url = "/docs/API/" -[[main]] - name = "Docs" - url = "/docs/prologue/introduction/" - weight = 10 +[[docs]] + name = "Help" + weight = 600 + identifier = "Help" + url = "/docs/help/" + + +######################## MAIN ############################## [[main]] name = "About" url = "/about/" - weight = 10 + weight = 100 [[main]] name = "Blog" url = "/blog/" - weight = 10 + weight = 20 [[main]] name = "Community" url = "/community/" - weight = 10 + weight = 30 [[main]] name = "Contact" url = "/contact/" - weight = 10 + weight = 40 + +[[main]] + name = "Docs" + url = "/docs/introduction/installing-captcha/" + weight = 500 [[social]] @@ -55,30 +69,30 @@ [[footer]] name = "About" url = "/about/" - weight = 10 + weight = 100 [[footer]] name = "Donate" url = "/donate" - weight = 10 + weight = 200 [[footer]] name = "Privacy" url = "/privacy-policy/" - weight = 10 - -[[footer]] - name = "Status" - url = "https://stats.uptimerobot.com/GK7VLFJnBl" - weight = 10 + weight = 300 [[footer]] name = "Security" url = "/security" identifier = "security" - weight = 10 + weight = 400 + +[[footer]] + name = "Status" + url = "https://stats.uptimerobot.com/GK7VLFJnBl" + weight = 500 [[footer]] name = "Thanks" url = "/thanks" - weight = 10 + weight = 600 diff --git a/content/docs/terminology/_index.md b/content/docs/terminology/_index.md new file mode 100644 index 0000000..4d4a5de --- /dev/null +++ b/content/docs/terminology/_index.md @@ -0,0 +1,9 @@ +--- +title : "Terminology" +description: "Information about terminology used in mCaptcha, some of which unique to the project" +lead: "" +date: 2022-07-27T08:48:45+00:00 +lastmod: 2020-07-27T08:48:45+00:00 +draft: false +images: [] +--- diff --git a/content/docs/terminology/access-token.md b/content/docs/terminology/access-token.md new file mode 100644 index 0000000..315bdbc --- /dev/null +++ b/content/docs/terminology/access-token.md @@ -0,0 +1,37 @@ +--- +title: "Access token" +description: "mCaptcha implements leaky bucket algorithm to measure +current traffic levels. Cooldown period specifies the leak or the time +after which a visitor addition is decremented." +lead: "" +date: 2022-07-22 +lastmod: 2022-07-22 20:17 +draft: false +images: [] +menu: + docs: + parent: "Terminology" +weight: 521 +toc: true +--- + +When a visitor solves the CAPTCHA and sends their solution to an +mCaptcha instance, the solution will be verified for correctness. If the +solution is correct, mCaptcha will return a single use access token. + +This access token should be attached to the visitor's requited to the +protected service and the protected service should validity of the +access token with the mCaptcha instance and only allow access to +protected resource if the access token is valid. + +## Validate access token: + +```bash +curl --location --request POST 'https://mcaptcha.example.net/api/v1/pow/siteverify' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "token": "replace this with the access token presented by visitor", + "key": "replace this with the sitekey associated with the CAPTCHA" + "secret": "replace this with mCaptcha account secret, available in settings" + }' +``` diff --git a/content/docs/terminology/cooldown-period.md b/content/docs/terminology/cooldown-period.md new file mode 100644 index 0000000..baa94ba --- /dev/null +++ b/content/docs/terminology/cooldown-period.md @@ -0,0 +1,32 @@ +--- +title: "Cooldown Period" +description: "mCaptcha implements leaky bucket algorithm to measure +current traffic levels. Cooldown period specifies the leak or the time +after which a visitor addition is decremented." +lead: "" +date: 2022-07-22 +lastmod: 2022-07-22 20:17 +draft: false +images: [] +menu: + docs: + parent: "Terminology" +weight: 522 +toc: true +--- + +mCaptcha implements leaky bucket algorithm to measure +current traffic levels. Cooldown period specifies the leak or the time +after which a visitor addition is decremented. + +For instance, if initial traffic level is 0 and a user visits one +second later, the traffic level will be incremented to 1. Now, if the +cooldown period is set to 30 seconds, the traffic level will be +decremented after 30 seconds. So after 30 seconds, the traffic level will +go from 1 to 0. + +## Easy Mode: Default cooldown + +When configuring mCaptcha in [easy +mode](./difficulty-factor#easy-option), the default cooldown period is +set to 30 seconds. diff --git a/content/docs/terminology/difficulty-factor/index.md b/content/docs/terminology/difficulty-factor/index.md new file mode 100644 index 0000000..3b24162 --- /dev/null +++ b/content/docs/terminology/difficulty-factor/index.md @@ -0,0 +1,23 @@ +--- +title: "Difficulty Factor" +description: "Difficulty factor determines the time it takes to solve a CAPTCHA, there are two modes to setting difficulty factor: advance and easy, this page documents both modes." +lead: "" +date: 2022-07-22 +lastmod: 2022-07-22 20:17 +draft: false +images: [] +menu: + docs: + parent: "Terminology" +weight: 523 +toc: true +--- + +Difficulty factor determines the time it takes to solve a CAPTCHA. The +higher the difficulty factor, the longer it will take to generate a +proof of work for it to solve the CAPTCHA. + +mCaptcha's proof of work based mechanism makes it highly accessible to +people with special needs but it is important to choose the difficulty factor +with care as very high difficulty factors will make the CAPTCHA +inaccessible to users on slow devices. diff --git a/content/docs/terminology/sitekey/copy-sitekey.png b/content/docs/terminology/sitekey/copy-sitekey.png new file mode 100644 index 0000000..4008dc9 Binary files /dev/null and b/content/docs/terminology/sitekey/copy-sitekey.png differ diff --git a/content/docs/terminology/sitekey/index.md b/content/docs/terminology/sitekey/index.md new file mode 100644 index 0000000..ce486a2 --- /dev/null +++ b/content/docs/terminology/sitekey/index.md @@ -0,0 +1,33 @@ +--- +title: "Site key" +description: "Site key is the unique identifier associated with a CAPTCHA created on mCaptcha" +lead: "" +date: 2022-07-22 +lastmod: 2022-07-22 20:17 +draft: false +images: [] +menu: + docs: + parent: "Terminology" +weight: 524 +toc: true +--- + +Site key is a unique identifier associated with CAPTCHA configurations +created on mCaptcha. It is required to integrate a CAPTCHA with your +website. + +## How to get site key? + +1. Go to "Site keys" on the side panel in the dashboard + +
+ +{{% img src="sitekey-in-dashboard-sidepanel.png" alt="Site key menu option on the dashboard, encircled in red." %}} + +
+ +2. click on the clipboard button to copy the site key to your + clipboard. + +{{% img src="copy-sitekey.png" alt="Copy site key to clipboard. Clipboard button is highlighted in the photo" %}} diff --git a/content/docs/terminology/sitekey/sitekey-in-dashboard-sidepanel.png b/content/docs/terminology/sitekey/sitekey-in-dashboard-sidepanel.png new file mode 100644 index 0000000..4745c79 Binary files /dev/null and b/content/docs/terminology/sitekey/sitekey-in-dashboard-sidepanel.png differ diff --git a/content/docs/terminology/visitor-threshold.md b/content/docs/terminology/visitor-threshold.md new file mode 100644 index 0000000..0191f7f --- /dev/null +++ b/content/docs/terminology/visitor-threshold.md @@ -0,0 +1,49 @@ +--- +title: "Visitor Threshold" +description: "Visitor threshold is used to split traffic into levels. If +the traffic level supersceedes the configured threshold, then mCaptcha will +increase difficulty factor based on the configuration provided." +lead: "" +date: 2022-07-22 +lastmod: 2022-07-22 20:17 +draft: false +images: [] +menu: + docs: + parent: "Terminology" +weight: 525 +toc: true +--- + +mCaptcha's variable difficulty factor mechanism requires a website's traffic +statistics be split into levels, so that it can deploy the right +difficulty factor for each level. + +Visitor threshold is used to traffic into levels and mCaptcha accepts a +difficulty configuration for each of these levels. When current traffic +exceeds a difficulty factor, mCaptcha will increase the difficulty +factor to the next configured level. + +For instance, consider the configuration given below: + +- Cool down period: 30 seconds + +| Level | Difficulty Factor | Visitor Threshold | +| ----- | ----------------- | ----------------- | +| 1 | 5,000 | 2,000 | +| 2 | 50,000 | 5,000 | +| 3 | 500,000 | 10,000 | +| 4 | 5,000,000 | 15,000 | + +If the website sees 2,000 requests in a 30 second window, level 1 +difficulty factor(5,000) will be deployed. If the traffic increases to +5,000 requests in a 30 second window, then difficulty factor will be +upgraded to level 2(50,000). Likewise 10,000 and 15,000 requests over 30 +seconds will result in difficulty factor being upgraded to 500,000 and +5,000,000 respectively. + +Visitor threshold is how mCaptcha determines which difficulty factor +level to deploy. mCaptcha uses leaky bucket algorithm to keep the +visitor threshold constantly updated within the configured cool down +period. So, at any given moment the, the current visitor level will be +the amount of traffic that was served in the cool down period specified.