Create a proper README #2

New Issue

cerealxp · 2023-06-12T11:49:34-04:00

cerealxp commented

2023-06-12 11:49:34 -04:00

Currently, the README shows how to the previous version of FreeCAPTCHA worked. That version of FreeCAPTCHA is documented here: https://www.turtle-techies.com/roll-your-own-captcha-python/.

This is no good for two reasons:

FreeCAPTCHA is very different now
We want to show a lot more.

Here is what I want to show, in order of priority:

Quick demonstration of what FreeCAPTCHA looks like for users when deployed
How webmasters (remember that word?) can integrate FreeCAPTCHA into their website (focusing on Tor onion services).
Document the architecture of FreeCAPTCHA graphically and explain the techniques (overlayed radio buttons, z-indexing, etc)

So here's the outline of how that should look

Intro
a. What is FreeCAPTCHA? (FOSS plug and play CAPTCHA for no-JS)
b. Why is it necessary? (replicate the behavior, quality, and security of commercial JS captchas, without the JS, because Tor users usually disable JS)
Demo
a. Show a gif demonstrating the use to access an onion service
b. Link to a video that does the same but shows the cookies as they come in and such
Howto
a. JS and Python blobs for calling FreeCAPTCHA API
b. PIP and NPM packages once they exist (middlewares)
c. HTML blurb for adding freecaptcha iframe to frontend (alternatively, the captcha solving page could be hosted by freecaptcha, and then redirects you to the real site once you've solved the captcha. Similar to how oauth redirects work)
Contributing
a. Diagram showing the relationship between users' servers and our own. Show each part of the architecture and where it is in relation to everything else.
b. Explain the z-indexing, overlaying checkbox CSS nonsense. (this also needs to be a separate issue where we try to find a real CSS master who can help us clearly understand and explain this lol)
c. How the cookies work (see JWT issue)
d. Security. Disclosing issues. Where weaknesses are likely to be and what kinds (where do we render input unsafely, jinja, possible jwt issues, rotating secret keys, architecture security, etc.) We should have a hall of fame for devs and seperate one for hackers with little trophies.

Currently, the README shows how to the previous version of FreeCAPTCHA worked. That version of FreeCAPTCHA is documented here: https://www.turtle-techies.com/roll-your-own-captcha-python/. This is no good for two reasons: 1. FreeCAPTCHA is very different now 2. We want to show a lot more. Here is what I want to show, in order of priority: 1. Quick demonstration of what FreeCAPTCHA looks like for users when deployed 2. How webmasters ([remember that word?](https://developers.google.com/search/blog/2020/11/goodbye-google-webmasters)) can integrate FreeCAPTCHA into their website (focusing on Tor onion services). 3. Document the architecture of FreeCAPTCHA graphically and explain the techniques (overlayed radio buttons, z-indexing, etc) So here's the outline of how that should look 1. Intro a. What is FreeCAPTCHA? (FOSS plug and play CAPTCHA for no-JS) b. Why is it necessary? (replicate the behavior, quality, and security of commercial JS captchas, without the JS, because Tor users usually disable JS) 2. Demo a. Show a gif demonstrating the use to access an onion service b. Link to a video that does the same but shows the cookies as they come in and such 3. Howto a. JS and Python blobs for calling FreeCAPTCHA API b. PIP and NPM packages once they exist (middlewares) c. HTML blurb for adding freecaptcha iframe to frontend (alternatively, the captcha solving page could be hosted by freecaptcha, and then redirects you to the real site once you've solved the captcha. Similar to how oauth redirects work) 4. Contributing a. Diagram showing the relationship between users' servers and our own. Show each part of the architecture and where it is in relation to everything else. b. Explain the z-indexing, overlaying checkbox CSS nonsense. (this also needs to be a separate issue where we try to find a real CSS master who can help us clearly understand and explain this lol) c. How the cookies work (see JWT issue) d. Security. Disclosing issues. Where weaknesses are likely to be and what kinds (where do we render input unsafely, jinja, possible jwt issues, rotating secret keys, architecture security, etc.) We should have a hall of fame for devs and seperate one for hackers with little trophies.

Sign in to join this conversation.