Add CAPTCHA verification support

Verifies cap-token from registration requests using the configured
Cap service when CAP_INSTANCE_URI and CAP_SECRET are set; otherwise
falls back to a no-op implementation.

Author: Kwarf

Cargo.lock

@@ -7,6 +7,8 @@ edition = "2024"
 axum = { version = "0.8", features = ["tokio"] }
 chrono = { version = "0.4", features = ["serde"] }
 constant_time_eq = "0.5"
+hyper = "1.10"
+reqwest = { version = "0.13", default-features = false, features = ["http2", "json"] }
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 sqlx = { version = "0.9", features = [

Cargo.toml

@@ -8,12 +8,14 @@ SQLite database.
 
 The following environment variables are used for configuration:
 
-| Variable    | Description                         | Default value  |
-|-------------|-------------------------------------|----------------|
-| API_KEY     | Key protecting the /admin endpoints |                |
-| CORS_ORIGIN | CORS preflight URL restriction      | *              |
-| SQLITE_DB   | Path to SQLite database file        | data.db        |
-| LISTEN_ADDR | IP and port to listen on            | 127.0.0.1:3000 |
+| Variable         | Description                         | Default value  |
+|------------------|-------------------------------------|----------------|
+| API_KEY          | Key protecting the /admin endpoints |                |
+| CORS_ORIGIN      | CORS preflight URL restriction      | *              |
+| SQLITE_DB        | Path to SQLite database file        | data.db        |
+| LISTEN_ADDR      | IP and port to listen on            | 127.0.0.1:3000 |
+| CAP_INSTANCE_URI | Cap site endpoint                   |                |
+| CAP_SECRET       | Cap site secret                     |                |
 
 ### Sample Docker Compose
 
@@ -65,6 +67,11 @@ date: Sat, 10 Jun 2023 19:16:20 GMT
 
 ### Registering as a visitor
 
+Due to problems with bots making spam registrations the `/register` endpoint can be configured to require a
+[proof-of-work](https://en.wikipedia.org/wiki/Proof_of_work) to be provided by the client using the self-hostable
+CAPTCHA tool [Cap](https://trycap.dev/). This is only enabled/required if **both** `CAP_INSTANCE_URI` and `CAP_SECRET`
+are set.
+
 Note that the fields `email` and `extra` are not shown in the public `GET /visitors` listing, but are intended only
 for the party organizers.
 
@@ -81,6 +88,27 @@ content-length: 0
 date: Sat, 10 Jun 2023 19:17:23 GMT
 ```
 
+#### With proof-of-work
+
+See the [Cap Quickstart](https://trycap.dev/guide/) for detailed information about how to add the Cap widget to your
+frontend.
+
+The `CAP_INSTANCE_URI` should point to the actual verification endpoint, like
+`https://<your-instance>/<site-key>/siteverify`. `CAP_SECRET` is your generated secret key, like `sk-xxx`.
+
+```sh
+curl -i -H 'Content-Type: application/json' \
+     -X POST \
+     -d '{"nick":"Lorem","group":"Ipsum","email":"lorem@example.com","extra":"Allergic to metaballs","cap-token":"fb69400c43:1ab132ceaeb7be79:d33ea92570f08527ba917c8ba24cc3"}' \
+     http://localhost:3000/register
+```
+
+```
+HTTP/1.1 201 Created
+content-length: 0
+date: Sat, 10 Jun 2023 19:17:23 GMT
+```
+
 ### Fetching full visitor data
 
 This is only available for organizers, authorized by API_KEY.

README.md

@@ -10,7 +10,7 @@ use constant_time_eq::constant_time_eq;
 use tower::ServiceBuilder;
 use tower_http::validate_request::{ValidateRequest, ValidateRequestHeaderLayer};
 
-use crate::{ApiState, db, error::ApiError, time::TimeService};
+use crate::{ApiState, captcha::CaptchaService, db, error::ApiError, time::TimeService};
 
 #[derive(Clone)]
 struct BearerTokenHeader {
@@ -20,7 +20,7 @@ struct BearerTokenHeader {
 impl BearerTokenHeader {
     fn new(key: &str) -> Self {
         Self {
-            key: HeaderValue::from_str(&format!("Bearer {}", key)).unwrap(),
+            key: HeaderValue::from_str(&format!("Bearer {key}")).unwrap(),
         }
     }
 
@@ -44,7 +44,7 @@ impl<B> ValidateRequest<B> for BearerTokenHeader {
     }
 }
 
-pub fn routes<T: TimeService>() -> Router<ApiState<T>> {
+pub fn routes<T: TimeService, C: CaptchaService>() -> Router<ApiState<T, C>> {
     match env::var("API_KEY") {
         Err(_) => {
             eprintln!("API_KEY not set, /admin endpoints will be disabled");
@@ -57,21 +57,21 @@ pub fn routes<T: TimeService>() -> Router<ApiState<T>> {
     }
 }
 
-async fn list_visitors<T: TimeService>(
-    State(state): State<ApiState<T>>,
+async fn list_visitors<T: TimeService, C: CaptchaService>(
+    State(state): State<ApiState<T, C>>,
 ) -> Result<(StatusCode, Json<Vec<db::Visitor>>), ApiError> {
-    let visitors = sqlx::query_as::<_, db::Visitor>(r#"SELECT * FROM visitor ORDER BY id"#)
+    let visitors = sqlx::query_as::<_, db::Visitor>(r"SELECT * FROM visitor ORDER BY id")
         .fetch_all(&state.db)
         .await?;
 
     Ok((StatusCode::OK, Json(visitors)))
 }
 
-async fn delete_visitor<T: TimeService>(
+async fn delete_visitor<T: TimeService, C: CaptchaService>(
     Path(id): Path<i32>,
-    State(state): State<ApiState<T>>,
+    State(state): State<ApiState<T, C>>,
 ) -> Result<StatusCode, ApiError> {
-    let rows = sqlx::query(r#"DELETE FROM visitor WHERE id = ?"#)
+    let rows = sqlx::query(r"DELETE FROM visitor WHERE id = ?")
         .bind(id)
         .execute(&state.db)
         .await?
@@ -93,7 +93,7 @@ mod test {
     use tower::ServiceExt;
 
     use crate::{
-        testing,
+        captcha, testing,
         time::{ConstantTimeService, TimeService},
     };
 
@@ -103,7 +103,7 @@ mod test {
 
         let time = ConstantTimeService::new();
         let db = testing::database().await;
-        let api = crate::api(time.clone(), db.clone());
+        let api = crate::api(time.clone(), captcha::NoOp::new(), db.clone());
 
         let response = api
             .oneshot(
@@ -126,11 +126,11 @@ mod test {
 
         let time = ConstantTimeService::new();
         let db = testing::database().await;
-        let api = crate::api(time.clone(), db.clone());
+        let api = crate::api(time.clone(), captcha::NoOp::new(), db.clone());
 
         testing::insert_visitor(&db, "Groupless", None).await;
 
-        testing::insert_visitor(&db, "With Group", Some("Awesome".into())).await;
+        testing::insert_visitor(&db, "With Group", Some("Awesome")).await;
 
         let response = api
             .oneshot(
@@ -171,7 +171,7 @@ mod test {
 
         let time = ConstantTimeService::new();
         let db = testing::database().await;
-        let api = crate::api(time.clone(), db.clone());
+        let api = crate::api(time.clone(), captcha::NoOp::new(), db.clone());
 
         let response = api
             .oneshot(
@@ -194,7 +194,7 @@ mod test {
 
         let time = ConstantTimeService::new();
         let db = testing::database().await;
-        let api = crate::api(time.clone(), db.clone());
+        let api = crate::api(time.clone(), captcha::NoOp::new(), db.clone());
 
         testing::insert_visitor(&db, "Groupless", None).await;
 

src/admin.rs

@@ -0,0 +1,89 @@
+use hyper::Uri;
+use serde::{Deserialize, Serialize};
+
+pub use cap::Cap;
+
+pub enum Error {
+    InvalidToken,
+    ServiceError(reqwest::Error),
+}
+
+impl From<reqwest::Error> for Error {
+    fn from(value: reqwest::Error) -> Self {
+        Error::ServiceError(value)
+    }
+}
+
+pub trait CaptchaService: Clone + Send + Sync + 'static {
+    fn verify(&self, token: &str) -> impl Future<Output = Result<(), Error>> + Send;
+}
+
+#[derive(Clone)]
+pub struct NoOp {}
+
+impl NoOp {
+    pub fn new() -> Self {
+        Self {}
+    }
+}
+
+impl CaptchaService for NoOp {
+    async fn verify(&self, _token: &str) -> Result<(), Error> {
+        Ok(())
+    }
+}
+
+mod cap {
+    #[allow(clippy::wildcard_imports)]
+    use super::*;
+
+    #[derive(Serialize)]
+    struct VerificationRequest<'a> {
+        secret: &'a str,
+        response: &'a str,
+    }
+
+    #[derive(Deserialize)]
+    struct VerificationResponse {
+        success: bool,
+    }
+
+    #[derive(Clone)]
+    pub struct Cap {
+        uri: Uri,
+        secret: String,
+    }
+
+    impl Cap {
+        pub fn new<S: Into<String>>(uri: Uri, secret: S) -> Self {
+            Self {
+                uri,
+                secret: secret.into(),
+            }
+        }
+    }
+
+    impl CaptchaService for Cap {
+        async fn verify(&self, token: &str) -> Result<(), Error> {
+            reqwest::Client::new()
+                .post(self.uri.to_string())
+                .json(&VerificationRequest {
+                    secret: &self.secret,
+                    response: token,
+                })
+                .send()
+                .await
+                .map_err(Error::from)?
+                .json::<VerificationResponse>()
+                .await
+                .map_err(Error::from)
+                .and_then(|response| {
+                    if response.success {
+                        Ok(())
+                    } else {
+                        Err(Error::InvalidToken)
+                    }
+                })
+        }
+    }
+}

src/captcha.rs

@@ -30,13 +30,13 @@ mod test {
     use hyper::{Request, StatusCode};
     use tower::ServiceExt;
 
-    use crate::{testing, time::ConstantTimeService};
+    use crate::{captcha, testing, time::ConstantTimeService};
 
     #[tokio::test]
     async fn should_allow_any_by_default() {
         let time = ConstantTimeService::new();
         let db = testing::database().await;
-        let api = crate::api(time.clone(), db.clone());
+        let api = crate::api(time.clone(), captcha::NoOp::new(), db.clone());
 
         let response = api
             .oneshot(
@@ -79,7 +79,7 @@ mod test {
 
         let time = ConstantTimeService::new();
         let db = testing::database().await;
-        let api = crate::api(time.clone(), db.clone());
+        let api = crate::api(time.clone(), captcha::NoOp::new(), db.clone());
 
         let response = api
             .oneshot(

src/cors.rs

@@ -1,13 +1,15 @@
 use std::borrow::Cow;
 
 use axum::{
+    Json,
     http::StatusCode,
     response::{IntoResponse, Response},
-    Json,
 };
 use serde::Serialize;
 use tower_governor::GovernorError;
 
+use crate::captcha;
+
 #[derive(Serialize)]
 pub(crate) struct ApiError {
     #[serde(skip_serializing)]
@@ -21,6 +23,21 @@ impl IntoResponse for ApiError {
     }
 }
 
+impl From<captcha::Error> for ApiError {
+    fn from(error: captcha::Error) -> Self {
+        match error {
+            captcha::Error::InvalidToken => Self {
+                code: StatusCode::BAD_REQUEST,
+                error: "captcha validation failed".to_owned(),
+            },
+            captcha::Error::ServiceError(_) => Self {
+                code: StatusCode::INTERNAL_SERVER_ERROR,
+                error: "captcha service unreachable".to_owned(),
+            },
+        }
+    }
+}
+
 impl From<sqlx::Error> for ApiError {
     fn from(error: sqlx::Error) -> Self {
         match error {