Release 2.1.0: security hardening across authentication, OAuth and administration

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "auth-api"
-version = "2.0.1"
+version = "2.1.0"
 edition = "2024"
 rust-version = "1.88"
 publish = false
@@ -44,6 +44,7 @@ ciborium = "0.2.2"
 form_urlencoded = "1.2"
 hmac = "0.13.0"
 sha2 = "0.11.0"
+subtle = "2.6"
 sqlx = { version = "0.8.6", default-features = false, features = ["runtime-tokio-rustls", "postgres", "uuid", "time", "derive", "json", "ipnetwork", "migrate"] }
 tera = { version = "2.0", features = ["glob_fs"] }
 thiserror = "2.0.18"
@@ -70,6 +71,7 @@ testkit = { path = "crates/testkit" }
 criterion = { version = "0.8.2", features = ["html_reports"] }
 futures = "0.3"
 proptest = "1.9.0"
+regex = "1"
 tokio = { version = "1.50.0", features = ["full", "test-util"] }
 tower = { version = "0.5.3", features = ["util"] }
 

Dockerfile

@@ -31,11 +31,11 @@ FROM chef AS builder
 COPY --from=planner /app/recipe.json recipe.json
 
 # Cache layer: compile dependencies only
-RUN cargo chef cook --release --recipe-path recipe.json
+RUN cargo chef cook --release --locked --recipe-path recipe.json
 
 # Compile the binary
 COPY . .
-RUN cargo build --release --bin auth-api
+RUN cargo build --release --locked --bin auth-api
 
 # =============================================================================
 # Stage 4: Runtime

Makefile

@@ -226,8 +226,8 @@ release: infra-check stack-test ## Build a signed release bundle in dist/ (VERSI
 	docker save auth-api:$(VERSION) | gzip > dist/auth-api-$(VERSION)/auth-api-$(VERSION).image.tar.gz
 	docker image inspect --format '{{.Id}}' auth-api:$(VERSION) > dist/auth-api-$(VERSION)/IMAGE_ID
 	git archive HEAD migrations docker-compose.api.yml docker-compose.api.l.yml config.prod.env \
-		nats.conf deploy/profiles deploy/db nginx/nginx.conf \
-		scripts/backup-db.sh scripts/restore-db.sh scripts/backup-drill.sh scripts/rolling-update.sh \
+		nats.conf deploy/profiles deploy/db deploy/api nginx/nginx.conf \
+		scripts/backup-db.sh scripts/restore-db.sh scripts/backup-drill.sh scripts/rolling-update.sh scripts/write-secrets.sh \
 		docs/deploy/guides/prometheus-alerts.yml deploy/monitoring | tar -x -C dist/auth-api-$(VERSION)
 	cd dist/auth-api-$(VERSION) && find . -type f ! -name 'SHA256SUMS*' -print0 | sort -z | xargs -0 sha256sum > SHA256SUMS
 	ssh-keygen -Y sign -q -f $(RELEASE_SIGNING_KEY) -n auth-api-release dist/auth-api-$(VERSION)/SHA256SUMS

benches/core_benches.rs

@@ -92,8 +92,9 @@ fn totp_benches(c: &mut Criterion) {
     let secret = totp::generate_secret();
     // The production path: a keyring and a versioned ciphertext.
     let keyring = auth_api::utils::crypto::Keyring::new([7u8; 32], None);
+    let owner = uuid::Uuid::nil();
     let encrypted = keyring
-        .encrypt(&secret)
+        .encrypt(&secret, owner.as_bytes())
         .expect("failed to encrypt benchmark secret");
 
     group.bench_function("generate_secret", |b| b.iter(totp::generate_secret));
@@ -111,6 +112,7 @@ fn totp_benches(c: &mut Criterion) {
             let code = totp::current_code(&secret).expect("code");
             totp::verify_code(
                 black_box(&encrypted),
+                owner,
                 black_box(&code),
                 black_box(&keyring),
                 1,

crates/testkit/src/app.rs

@@ -374,7 +374,18 @@ impl TestApp {
     /// Delete the anti-spam cooldown of email 2FA, so the next login can send
     /// a code right away.
     pub async fn clear_email_2fa_cooldown(&self, user_id: uuid::Uuid) {
-        self.delete_redis_key(&format!("email2fa_cd:{user_id}"))
+        // The setup cooldown, each challenge's, and the account's hourly
+        // budget of sign-in codes.
+        if let Ok(mut conn) = self.redis.get().await {
+            let keys: Vec<String> = conn
+                .keys(format!("email2fa_cd:{user_id}*"))
+                .await
+                .unwrap_or_default();
+            if !keys.is_empty() {
+                let _: Result<(), _> = conn.del(keys).await;
+            }
+        }
+        self.delete_redis_key(&format!("email2fa_send_user:{user_id}"))
             .await;
     }
 
@@ -384,25 +395,40 @@ impl TestApp {
 
         let mut conn = self.redis.get().await.expect("redis connection failed");
         let raw: String = conn
-            .get(format!("email_change_flow:{flow_token}"))
+            .get(format!(
+                "email_change_flow:{}",
+                auth_api::utils::crypto::token_id(flow_token)
+            ))
             .await
             .expect("email_change flow state not found in Redis");
 
         let state: serde_json::Value = serde_json::from_str(&raw).unwrap();
+        let user_id: uuid::Uuid = state["user_id"].as_str().unwrap().parse().unwrap();
         let hash_b64 = state["otp_hash"]
             .as_str()
             .expect("otp_hash missing from flow state");
         let hash_bytes = base64::engine::general_purpose::URL_SAFE_NO_PAD
             .decode(hash_b64)
             .unwrap();
 
-        brute_force_otp(&hash_bytes)
+        brute_force_otp(&hash_bytes, |code| {
+            self.state
+                .keyring
+                .otp_digest("email_change", user_id.as_bytes(), code)
+        })
     }
 
     /// Clear the per-user email-change cooldown so a second flow can start.
     pub async fn clear_email_change_cooldown(&self, user_id: uuid::Uuid) {
         self.delete_redis_key(&format!("email_change_cd:{user_id}"))
             .await;
+        self.clear_email_change_start_cooldown(user_id).await;
+    }
+
+    /// Lift the minute between two starts of an e-mail change.
+    pub async fn clear_email_change_start_cooldown(&self, user_id: uuid::Uuid) {
+        self.delete_redis_key(&format!("email_change_start_cd:{user_id}"))
+            .await;
     }
 
     pub async fn clear_recent_reauth(&self, access_token: &str) {
@@ -520,12 +546,16 @@ pub fn test_config(db_url: &str, redis_url: &str, nats_url: &str) -> Config {
             sensitive_action_reauth_secs: 600,
             new_device_alerts: true,
             magic_links: true,
+            registrations_per_ip_per_hour: 10_000,
+            reset_revokes_factors_added_hours: 72,
         },
         captcha: CaptchaConfig {
             secret: None,
             verify_url: "https://hcaptcha.com/siteverify".into(),
             request_timeout_secs: 1,
             fail_open_on_error: false,
+            site_key: None,
+            expected_hostnames: Vec::new(),
         },
         cors: CorsConfig {
             allowed_origins: vec!["*".into()],
@@ -594,17 +624,21 @@ pub fn test_config(db_url: &str, redis_url: &str, nats_url: &str) -> Config {
         },
         metrics: MetricsConfig {
             enabled: false,
+            host: "127.0.0.1".into(),
             port: 9464,
+            token: None,
         },
     }
 }
 
 /// Recover a 6-digit OTP from its SHA-256 digest.
-pub fn brute_force_otp(expected_hash: &[u8]) -> String {
-    use sha2::{Digest, Sha256};
+/// The six-digit code whose digest, by `digest`, is `expected_hash`: tests
+/// hold the application keyring, an attacker holding only the stored digest
+/// does not.
+pub fn brute_force_otp(expected_hash: &[u8], digest: impl Fn(&str) -> [u8; 32]) -> String {
     (0u32..1_000_000)
         .map(|n| format!("{n:06}"))
-        .find(|candidate| Sha256::digest(candidate.as_bytes()).as_slice() == expected_hash)
+        .find(|candidate| digest(candidate).as_slice() == expected_hash)
         .expect("OTP not found in the 6-digit space")
 }
 
@@ -659,6 +693,7 @@ mod tests {
     #[test]
     fn otp_is_recovered_from_its_digest() {
         use sha2::{Digest, Sha256};
-        assert_eq!(brute_force_otp(&Sha256::digest(b"004217")), "004217");
+        let digest = |code: &str| -> [u8; 32] { Sha256::digest(code.as_bytes()).into() };
+        assert_eq!(brute_force_otp(&digest("004217"), digest), "004217");
     }
 }

crates/testkit/src/mailpit.rs

@@ -73,7 +73,11 @@ impl MailpitClient {
     pub async fn wait_for_message(&self, email: &str, subject: &str) -> Option<MessageDetail> {
         // Record "now" before we start polling so we can discard any pre-existing
         // messages that happen to match the same email + subject.
-        let not_before = time::OffsetDateTime::now_utc() - time::Duration::milliseconds(500); // small back-buffer for clock skew
+        // Back-buffer: the message may have been sent a while before this call
+        // (padded responses, the contract validators built on a process's
+        // first request). Addresses are unique per test, so older messages
+        // to the same address come from earlier runs, seconds before.
+        let not_before = time::OffsetDateTime::now_utc() - time::Duration::seconds(3);
 
         let deadline = std::time::Instant::now() + std::time::Duration::from_millis(5_000);
         while std::time::Instant::now() < deadline {

crates/verifier/tests/verify.rs

@@ -76,8 +76,8 @@ async fn forged_expired_and_foreign_tokens_are_refused() {
 async fn introspection_catches_a_token_revoked_before_it_expires() {
     let app = TestApp::spawn().await;
     sqlx::query(
-        "INSERT INTO registered_clients (client_id, display_name, client_secret_hash)
-         VALUES ('resource-server', 'Resource server', $1)",
+        "INSERT INTO registered_clients (client_id, display_name, client_secret_hash, allows_introspection)
+         VALUES ('resource-server', 'Resource server', $1, TRUE)",
     )
     .bind(auth_api::utils::crypto::sha256(b"aacs_rs-secret").to_vec())
     .execute(&app.db)

deploy/api/logrotate-auth-api

@@ -0,0 +1,21 @@
+# Rotation of the auth-api access log: 14 days at most. The log holds client
+# addresses and user agents; keeping them longer than the application keeps
+# full addresses in its audit log would undo its retention policy
+# (docs/dev/privacy.md). Takes precedence over the nginx package's weekly
+# rotation of /var/log/nginx/*.log for this file.
+#
+# Install: sudo install -m 644 deploy/api/logrotate-auth-api /etc/logrotate.d/auth-api
+# Check:   sudo logrotate --debug /etc/logrotate.d/auth-api
+/var/log/nginx/auth-api.access.log {
+    daily
+    rotate 14
+    missingok
+    notifempty
+    compress
+    delaycompress
+    create 0640 www-data adm
+    sharedscripts
+    postrotate
+        invoke-rc.d nginx rotate >/dev/null 2>&1 || true
+    endscript
+}

deploy/api/nftables-auth-api.conf

@@ -0,0 +1,30 @@
+# Only nginx (and root, for the rolling update's readiness checks) reaches the
+# API instances on the API VPS. Docker publishes them on 127.0.0.1:3001-3004,
+# and the application trusts X-Forwarded-For from the address those
+# connections arrive with: without this rule, any other process on the host
+# could forge a client address and bypass the per-address limits.
+#
+# Install (docs/deploy/api/deployment.md):
+#   sudo install -m 644 deploy/api/nftables-auth-api.conf /etc/nftables.d/auth-api.conf
+#   echo 'include "/etc/nftables.d/*.conf"' | sudo tee -a /etc/nftables.conf
+#   sudo systemctl enable --now nftables && sudo nft -f /etc/nftables.conf
+#
+# The instances are also reachable at their own addresses on the compose
+# bridge (172.30.0.0/24), where connections arrive from the gateway
+# 172.30.0.1 - the trusted proxy. The second rule closes that path too, for the
+# application port and the internal listener; it also covers the published
+# ports when Docker rewrites them to the bridge (userland proxy disabled).
+#
+# Check: `sudo -u nobody curl -s 127.0.0.1:3001/live` and
+# `sudo -u nobody curl -s 172.30.0.2:3000/live` are refused, while
+# `sudo curl -fsS 127.0.0.1:3001/live` and `curl -fsS https://<host>/live` answer.
+# www-data is the user nginx workers run as on Debian; the Docker port proxy
+# runs as root.
+
+table inet auth_api_local {
+    chain output {
+        type filter hook output priority 0; policy accept;
+        oifname "lo" tcp dport 3001-3004 meta skuid != { 0, "www-data" } reject with tcp reset
+        ip daddr 172.30.0.0/24 tcp dport { 3000, 9464 } meta skuid != { 0, "www-data" } reject with tcp reset
+    }
+}

deploy/db/auth-api-grants.sql

@@ -0,0 +1,62 @@
+-- Privileges of the runtime role `auth_api` on a schema owned by
+-- `auth_api_owner` (docs/deploy/database/deployment.md, section 2.1). Run as
+-- postgres in the auth-api database, after the first migration run:
+--   sudo -u postgres psql -d auth_api -f auth-api-grants.sql
+-- Running it again is harmless. Later migrations run as `auth_api_owner` and
+-- the default privileges below extend to the tables they create.
+--
+-- The runtime role reads and writes data and nothing else: it cannot alter,
+-- drop or truncate a table, disable a trigger, rewrite the audit log, change
+-- the permission catalog or the migration history. A compromised application
+-- or an SQL injection is bounded by that.
+
+GRANT USAGE ON SCHEMA public TO auth_api;
+GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO auth_api;
+GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO auth_api;
+-- The functions running with the owner's privileges are granted by name: a
+-- function added later runs for the application only once listed here. Every
+-- other function keeps PostgreSQL's default EXECUTE for everyone.
+GRANT EXECUTE ON FUNCTION
+    rotate_audit_log_partitions(INTEGER, INTEGER),
+    forget_account_traces(UUID),
+    purge_unverified_accounts(INTERVAL, INTEGER),
+    coarsen_audit_addresses(INTERVAL, INTEGER),
+    cleanup_published_events(INTERVAL, INTEGER),
+    cleanup_finished_webhook_deliveries(INTERVAL, INTEGER)
+TO auth_api;
+
+ALTER DEFAULT PRIVILEGES FOR ROLE auth_api_owner IN SCHEMA public
+    GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO auth_api;
+ALTER DEFAULT PRIVILEGES FOR ROLE auth_api_owner IN SCHEMA public
+    GRANT USAGE, SELECT ON SEQUENCES TO auth_api;
+
+-- The audit log is append-only for the application: rows are rewritten only
+-- by the maintenance functions of the migrations, which run as the owner, and removed only
+-- with their partition.
+REVOKE UPDATE, DELETE ON audit_log FROM auth_api;
+DO $$
+DECLARE
+    partition RECORD;
+BEGIN
+    FOR partition IN
+        SELECT c.relname FROM pg_inherits i
+        JOIN pg_class c ON c.oid = i.inhrelid
+        JOIN pg_class p ON p.oid = i.inhparent
+        WHERE p.relname = 'audit_log'
+    LOOP
+        EXECUTE format('REVOKE UPDATE, DELETE ON %I FROM auth_api', partition.relname);
+    END LOOP;
+END
+$$;
+
+-- Outgoing events and webhook deliveries leave only through the owner's
+-- retention functions: the runtime role marks them sent or failed, never
+-- deletes them, so an unpublished `user.deleted` cannot be made to vanish.
+REVOKE DELETE ON event_outbox, webhook_deliveries FROM auth_api;
+
+-- The permission catalog and the migration history change with migrations only.
+REVOKE INSERT, UPDATE, DELETE ON permissions FROM auth_api;
+REVOKE INSERT, UPDATE, DELETE ON _sqlx_migrations FROM auth_api;
+-- The minimums of the maintenance functions are the owner's to change: the
+-- runtime role calls the functions but cannot lower what they keep.
+REVOKE INSERT, UPDATE, DELETE ON maintenance_floors FROM auth_api;

deploy/db/auth-api-role.sql

@@ -3,8 +3,8 @@
 --
 -- A statement or a lock wait gives up before the API's own 30-second request
 -- timeout, and a connection left idle inside a transaction is closed instead of
--- holding its locks. Migrations lift the statement timeout for their own
--- session (see docs/deploy/database/deployment.md, section 2.5).
+-- holding its locks. Migrations run as `auth_api_owner`, which carries no
+-- such limit (see docs/deploy/database/deployment.md, section 2.5).
 ALTER ROLE auth_api SET statement_timeout = '25s';
 ALTER ROLE auth_api SET lock_timeout = '10s';
 ALTER ROLE auth_api SET idle_in_transaction_session_timeout = '60s';

deploy/db/pg_hba.auth-api.conf

@@ -0,0 +1,12 @@
+# Access rules of the auth-api database, appended to
+# /etc/postgresql/17/main/pg_hba.conf (docs/deploy/database/deployment.md,
+# section 2.2). Only the API VPS, through its WireGuard address, and only with
+# a password (SCRAM): no `trust`, no wider network. Rules are read top down:
+# nothing above them may grant more.
+#
+# Where the tunnel is not the trust boundary, write `hostssl` instead of `host`
+# and add `sslmode=verify-full` to both connection URLs.
+
+# TYPE  DATABASE    USER              ADDRESS        METHOD
+host    auth_api    auth_api          10.0.0.1/32    scram-sha-256
+host    auth_api    auth_api_owner    10.0.0.1/32    scram-sha-256