Temporary usertokens via proof-of-work challenge (khanon/oai-reverse-proxy!68)

docs/pow-captcha.md

@@ -0,0 +1,95 @@
+# Proof-of-work Verification
+
+You can require users to complete a proof-of-work before they can access the
+proxy. This can increase the cost of denial of service attacks and slow down
+automated abuse.
+
+When configured, users access the challenge UI and request a proof of work. The
+server will generate a challenge according to the difficulty level you have set.
+The user can then start the worker to solve the challenge. Once the challenge is
+solved, the user can submit the solution to the server. The server will verify
+the solution and issue a temporary token for that user.
+
+## Configuration
+
+To enable proof-of-work verification, set the following environment variables:
+
+```
+GATEKEEPER=user_token
+CAPTCHA_MODE=proof_of_work
+# Validity of the token in hours
+POW_TOKEN_HOURS=24
+# Max number of IPs that can use a user_token issued via proof-of-work
+POW_TOKEN_MAX_IPS=2
+# The difficulty level of the proof-of-work challenge
+POW_DIFFICULTY_LEVEL=low
+```
+
+## Difficulty Levels
+
+The difficulty level controls how long it takes to solve the proof-of-work,
+specifically by adjusting the average number of iterations required to find a
+valid solution. Due to randomness, the actual number of iterations required can
+vary significantly.
+
+You can adjust the difficulty while the proxy is running from the admin interface.
+
+### Extreme
+
+- Average of 4000 iterations required
+- Not recommended unless you are expecting very high levels of abuse
+
+### High
+
+- Average of 1900 iterations required
+
+### Medium
+
+- Average of 900 iterations required
+
+### Low
+
+- Average of 200 iterations required
+- Default setting.
+
+## Custom argon2id parameters
+
+You can set custom argon2id parameters for the proof-of-work challenge.
+Generally, you should not need to change these unless you have a specific
+reason to do so.
+
+The listed values are the defaults.
+
+```
+ARGON2_TIME_COST=8
+ARGON2_MEMORY_KB=65536
+ARGON2_PARALLELISM=1
+ARGON2_HASH_LENGTH=32
+```
+
+Increasing parallelism will not do much except increase memory consumption for
+both the client and server, because browser proof-of-work implementations are
+single-threaded. It's better to increase the time cost if you want to increase
+the difficulty.
+
+Increasing memory too much may cause memory exhaustion on some mobile devices,
+particularly on iOS due to the way Safari handles WebAssembly memory allocation.
+
+## Tested hash rates
+
+These were measured with the default argon2id parameters listed above. These
+tests were not at all scientific so take them with a grain of salt.
+
+Safari does not like large WASM memory usage, so concurrency is limited to 4 to
+avoid overallocating memory on mobile WebKit browsers. Thermal throttling can
+also significantly reduce hash rates on mobile devices.
+
+- Intel Core i9-13900K (Chrome): 33-35 H/s
+- Intel Core i9-13900K (Firefox): 29-32 H/s
+- Intel Core i9-13900K (Chrome, in VM limited to 4 cores): 12.2 - 13.0 H/s
+- iPad Pro (M2) (Safari, 6 workers): 8.0 - 10 H/s
+  - Thermal throttles early. 8 cores is normal concurrency, but unstable.
+- iPhone 13 Pro (Safari): 4.0 - 4.6 H/s
+- Samsung Galaxy S10e (Chrome): 3.6 - 3.8 H/s
+  - This is a 2019 phone almost matching an iPhone five years newer because of
+    bad Safari performance.

docs/user-management.md

@@ -12,6 +12,7 @@ Several of these features require you to set secrets in your environment. If usi
   - [Memory](#memory)
   - [Firebase Realtime Database](#firebase-realtime-database)
     - [Firebase setup instructions](#firebase-setup-instructions)
+- [Whitelisting admin IP addresses](#whitelisting-admin-ip-addresses)
 
 ## No user management (`GATEKEEPER=none`)
 
@@ -61,3 +62,12 @@ To use Firebase Realtime Database to persist user data, set the following enviro
 8. Set `GATEKEEPER_STORE` to `firebase_rtdb` in your environment if you haven't already.
 
 The proxy server will attempt to connect to your Firebase Realtime Database at startup and will throw an error if it cannot connect. If you see this error, check that your `FIREBASE_RTDB_URL` and `FIREBASE_KEY` secrets are set correctly.
+
+## Whitelisting admin IP addresses
+You can add your own IP ranges to the `ADMIN_WHITELIST` environment variable for additional security.
+
+You can provide a comma-separated list containing individual IPv4 or IPv6 addresses, or CIDR ranges.
+
+To whitelist an entire IP range, use CIDR notation. For example, `192.168.0.1/24` would whitelist all addresses from `192.168.0.0` to `192.168.0.255`.
+
+To disable the whitelist, set `ADMIN_WHITELIST=0.0.0.0/0`, which will allow access from any IP address. This is the default behavior.