From 71fd3095aa2dcbb34737b592fd8ad6a539d6c60a Mon Sep 17 00:00:00 2001 From: Runxi Yu Date: Sun, 23 Mar 2025 13:12:31 +0800 Subject: More detailed README --- README.md | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 13492dc..7dd075f 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,8 @@ # Powxy – anti-scraper reverse proxy -Powxy uses a SHA-256 proof-of-work challenge to protect upstream resources from -scraper bots. +Powxy is a reverse proxy that sits in front of your upstream service and +enforces a SHA-256 proof-of-work challenge. The goal is to discourage scraping, +as it becomes expensive for a client to perform en masse. ## Demo @@ -49,6 +50,27 @@ Usage of ./powxy: destination url base to proxy to (default "http://127.0.0.1:8080") ``` +## Mechanism + +The client sends a request to the proxy. The proxy hashes information about the +client's IP address and user agent to generate an identifier. It checks whether +the client has a cookie containing an HMAC of the identifier. The connection is +forwarded to the upstream server if and only if the identifier matches and the +HMAC is valid. + +Otherwise, the client is presented with a challenge, which asks them to find +a nonce that, when appended to the identifier, results in a SHA-256 hash that +begins with a certain number of zero bits. The client must solve the challenge +and submit it through an HTML form, which is then validated by the proxy. If +validation passes, the client is issued a cookie containing their identifier +and its HMAC, and is redirected to request the page again, this time with the +necessary cookie to pass the validation. + +JavaScript is provided to automatically solve the challenge without user +interaction. Clients that do not run JavaScript need to solve the challenge +externally, e.g. via the C program provided near the HTML form, and submit +their nonce manually. + ## Contribute Create a branch that begins with `contrib/` and push to -- cgit v1.2.3