refactor(relay): eliminate DRY violations across admin route handlers

Extract shared admin Bearer token validation, code generation, and test
helpers that were duplicated across claim_codes, create_account, and
create_signing_key.

- routes/auth.rs: require_admin_token() replaces 37-line auth block copied 3×;
also fixes create_signing_key which was missing the inspect_err debug log
for non-UTF-8 Authorization headers
- routes/code_gen.rs: generate_code() + CODE_LEN/CHARSET moved here from
claim_codes and create_account where they were defined identically
- routes/test_utils.rs: test_state_with_admin_token() shared instead of
duplicated in each route's test module
- create_account: consolidate 4 separate pre-check queries into 2 OR EXISTS
queries (email and handle each check both tables in one round-trip)

crates/relay/src/routes/auth.rs

···
+use axum::http::HeaderMap;
+use subtle::ConstantTimeEq;
+
+use common::{ApiError, ErrorCode};
+
+use crate::app::AppState;
+
+/// Validate the admin Bearer token from request headers.
+///
+/// Returns `Ok(())` when the token is present, has the `"Bearer "` prefix, and matches
+/// `Config.admin_token` in constant time. Returns `ApiError::Unauthorized` in all other
+/// cases, including when the server has no token configured.
+///
+/// Call this at the top of any handler that requires admin access.
+pub fn require_admin_token(headers: &HeaderMap, state: &AppState) -> Result<(), ApiError> {
+    let expected_token = state
+        .config
+        .admin_token
+        .as_deref()
+        .ok_or_else(|| ApiError::new(ErrorCode::Unauthorized, "admin token not configured"))?;
+
+    let auth_value = headers
+        .get(axum::http::header::AUTHORIZATION)
+        .and_then(|v| {
+            v.to_str()
+                .inspect_err(|_| {
+                    tracing::debug!(
+                        "Authorization header contains non-UTF-8 bytes; treating as absent"
+                    );
+                })
+                .ok()
+        })
+        .unwrap_or("");
+
+    let provided_token = auth_value.strip_prefix("Bearer ").ok_or_else(|| {
+        ApiError::new(
+            ErrorCode::Unauthorized,
+            "missing or invalid Authorization header",
+        )
+    })?;
+
+    if provided_token
+        .as_bytes()
+        .ct_eq(expected_token.as_bytes())
+        .unwrap_u8()
+        != 1
+    {
+        return Err(ApiError::new(ErrorCode::Unauthorized, "invalid admin token"));
+    }
+
+    Ok(())
+}

crates/relay/src/routes/claim_codes.rs

···
 // pattern: Imperative Shell
 //
-// Gathers: Bearer token from Authorization header, JSON request body, config, DB pool
+// Gathers: admin Bearer token (Authorization header), JSON request body, DB pool
 // Processes: auth check → input validation → code generation → DB batch insert (transaction)
 // Returns: JSON { codes: [...] } on success; ApiError on all failure paths
 
 use axum::{extract::State, http::HeaderMap, response::Json};
-use rand_core::{OsRng, RngCore};
 use serde::{Deserialize, Serialize};
-use subtle::ConstantTimeEq;
 
 use common::{ApiError, ErrorCode};
 
 use crate::app::AppState;
+use crate::routes::auth::require_admin_token;
+use crate::routes::code_gen::generate_code;
 
 const MAX_COUNT: u32 = 10;
-const CODE_LEN: usize = 6;
-const CHARSET: &[u8] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
 
 fn default_expires_in_hours() -> u32 {
     24
···
 ) -> Result<Json<ClaimCodesResponse>, ApiError> {
     // --- Auth: require matching Bearer token ---
     // Check this first so unauthenticated callers cannot probe server configuration.
-    let expected_token = state
-        .config
-        .admin_token
-        .as_deref()
-        .ok_or_else(|| ApiError::new(ErrorCode::Unauthorized, "admin token not configured"))?;
-
-    let auth_value = headers
-        .get(axum::http::header::AUTHORIZATION)
-        .and_then(|v| {
-            v.to_str()
-                .inspect_err(|_| {
-                    tracing::debug!(
-                        "Authorization header contains non-UTF-8 bytes; treating as absent"
-                    );
-                })
-                .ok()
-        })
-        .unwrap_or("");
-
-    let provided_token = auth_value.strip_prefix("Bearer ").ok_or_else(|| {
-        ApiError::new(
-            ErrorCode::Unauthorized,
-            "missing or invalid Authorization header",
-        )
-    })?;
-
-    if provided_token
-        .as_bytes()
-        .ct_eq(expected_token.as_bytes())
-        .unwrap_u8()
-        != 1
-    {
-        return Err(ApiError::new(
-            ErrorCode::Unauthorized,
-            "invalid admin token",
-        ));
-    }
+    require_admin_token(&headers, &state)?;
 
     // --- Validate input ---
     if payload.count == 0 || payload.count > MAX_COUNT {
···
     codes.into_iter().collect()
 }
 
-/// Generate a single 6-character uppercase alphanumeric code.
-fn generate_code() -> String {
-    let mut buf = [0u8; CODE_LEN];
-    OsRng.fill_bytes(&mut buf);
-    buf.iter()
-        .map(|&b| CHARSET[(b as usize) % CHARSET.len()] as char)
-        .collect()
-}
-
 /// Insert all codes in a single transaction; returns Err if any INSERT fails.
 async fn insert_claim_codes(
     db: &sqlx::SqlitePool,
···
 
 #[cfg(test)]
 mod tests {
-    use std::sync::Arc;
-
     use axum::{
         body::Body,
         http::{Request, StatusCode},
     };
     use tower::ServiceExt;
 
-    use crate::app::{app, test_state, AppState};
+    use crate::app::{app, test_state};
+    use crate::routes::test_utils::test_state_with_admin_token;
 
     // ── Helpers ──────────────────────────────────────────────────────────────
-
-    async fn test_state_with_admin_token() -> AppState {
-        let base = test_state().await;
-        let mut config = (*base.config).clone();
-        config.admin_token = Some("test-admin-token".to_string());
-        AppState {
-            config: Arc::new(config),
-            db: base.db,
-        }
-    }
 
     fn post_claim_codes(body: &str, bearer: Option<&str>) -> Request<Body> {
         let mut builder = Request::builder()

crates/relay/src/routes/code_gen.rs

···
+use rand_core::{OsRng, RngCore};
+
+pub const CODE_LEN: usize = 6;
+pub const CHARSET: &[u8] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+
+/// Generate a single 6-character uppercase alphanumeric code.
+pub fn generate_code() -> String {
+    let mut buf = [0u8; CODE_LEN];
+    OsRng.fill_bytes(&mut buf);
+    buf.iter()
+        .map(|&b| CHARSET[(b as usize) % CHARSET.len()] as char)
+        .collect()
+}

crates/relay/src/routes/create_account.rs

···
 // pattern: Imperative Shell
 //
-// Gathers: Bearer token from Authorization header, JSON request body, config, DB pool
+// Gathers: admin Bearer token (Authorization header), JSON request body, config, DB pool
 // Processes: auth check → handle validation → tier validation → email uniqueness →
 //            handle uniqueness → account_id generation → claim code generation →
 //            DB transaction (claim_codes + pending_accounts insert)
···
     http::{HeaderMap, StatusCode},
     response::Json,
 };
-use rand_core::{OsRng, RngCore};
 use serde::{Deserialize, Serialize};
-use subtle::ConstantTimeEq;
 use uuid::Uuid;
 
 use common::{ApiError, ErrorCode};
 
 use crate::app::AppState;
+use crate::routes::auth::require_admin_token;
+use crate::routes::code_gen::generate_code;
 
-const CODE_LEN: usize = 6;
-const CHARSET: &[u8] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
 const CLAIM_CODE_EXPIRES_IN_HOURS: u32 = 24;
 
 #[derive(Deserialize)]
···
     Json(payload): Json<CreateAccountRequest>,
 ) -> Result<(StatusCode, Json<CreateAccountResponse>), ApiError> {
     // --- Auth: require matching Bearer token ---
-    let expected_token = state
-        .config
-        .admin_token
-        .as_deref()
-        .ok_or_else(|| ApiError::new(ErrorCode::Unauthorized, "admin token not configured"))?;
-
-    let auth_value = headers
-        .get(axum::http::header::AUTHORIZATION)
-        .and_then(|v| {
-            v.to_str()
-                .inspect_err(|_| {
-                    tracing::debug!(
-                        "Authorization header contains non-UTF-8 bytes; treating as absent"
-                    );
-                })
-                .ok()
-        })
-        .unwrap_or("");
-
-    let provided_token = auth_value.strip_prefix("Bearer ").ok_or_else(|| {
-        ApiError::new(
-            ErrorCode::Unauthorized,
-            "missing or invalid Authorization header",
-        )
-    })?;
-
-    if provided_token
-        .as_bytes()
-        .ct_eq(expected_token.as_bytes())
-        .unwrap_u8()
-        != 1
-    {
-        return Err(ApiError::new(ErrorCode::Unauthorized, "invalid admin token"));
-    }
+    require_admin_token(&headers, &state)?;
 
     // --- Validate handle format ---
     if let Err(msg) = validate_handle(&payload.handle) {
···
         ));
     }
 
-    // --- Email uniqueness: check accounts and pending_accounts ---
-    let email_in_accounts: bool = sqlx::query_scalar(
-        "SELECT EXISTS(SELECT 1 FROM accounts WHERE email = ?)",
+    // --- Email uniqueness: check accounts and pending_accounts in one query ---
+    // Fast-path optimization: reject before the INSERT to avoid touching the claim code retry
+    // loop on a predictable failure. The unique indexes on pending_accounts.email and
+    // accounts.email are the authoritative enforcement; this is an early return.
+    // Note: pending_accounts has no cross-table FK to accounts, so both tables must be checked.
+    let email_taken: bool = sqlx::query_scalar(
+        "SELECT EXISTS(SELECT 1 FROM accounts WHERE email = ?)
+             OR EXISTS(SELECT 1 FROM pending_accounts WHERE email = ?)",
     )
     .bind(&payload.email)
-    .fetch_one(&state.db)
-    .await
-    .map_err(|e| {
-        tracing::error!(error = %e, "failed to check email uniqueness in accounts");
-        ApiError::new(ErrorCode::InternalError, "failed to create account")
-    })?;
-
-    let email_in_pending: bool = sqlx::query_scalar(
-        "SELECT EXISTS(SELECT 1 FROM pending_accounts WHERE email = ?)",
-    )
     .bind(&payload.email)
     .fetch_one(&state.db)
     .await
     .map_err(|e| {
-        tracing::error!(error = %e, "failed to check email uniqueness in pending_accounts");
+        tracing::error!(error = %e, "failed to check email uniqueness");
         ApiError::new(ErrorCode::InternalError, "failed to create account")
     })?;
 
-    if email_in_accounts || email_in_pending {
+    if email_taken {
         return Err(ApiError::new(
             ErrorCode::AccountExists,
             "an account with this email already exists",
         ));
     }
 
-    // --- Handle uniqueness: check handles and pending_accounts ---
-    let handle_in_handles: bool = sqlx::query_scalar(
-        "SELECT EXISTS(SELECT 1 FROM handles WHERE handle = ?)",
+    // --- Handle uniqueness: check handles and pending_accounts in one query ---
+    let handle_taken: bool = sqlx::query_scalar(
+        "SELECT EXISTS(SELECT 1 FROM handles WHERE handle = ?)
+             OR EXISTS(SELECT 1 FROM pending_accounts WHERE handle = ?)",
     )
     .bind(&payload.handle)
-    .fetch_one(&state.db)
-    .await
-    .map_err(|e| {
-        tracing::error!(error = %e, "failed to check handle uniqueness in handles");
-        ApiError::new(ErrorCode::InternalError, "failed to create account")
-    })?;
-
-    let handle_in_pending: bool = sqlx::query_scalar(
-        "SELECT EXISTS(SELECT 1 FROM pending_accounts WHERE handle = ?)",
-    )
     .bind(&payload.handle)
     .fetch_one(&state.db)
     .await
     .map_err(|e| {
-        tracing::error!(error = %e, "failed to check handle uniqueness in pending_accounts");
+        tracing::error!(error = %e, "failed to check handle uniqueness");
         ApiError::new(ErrorCode::InternalError, "failed to create account")
     })?;
 
-    if handle_in_handles || handle_in_pending {
+    if handle_taken {
         return Err(ApiError::new(
             ErrorCode::HandleTaken,
             "this handle is already claimed",
···
     matches!(tier, "free" | "pro" | "business")
 }
 
-/// Generate a single 6-character uppercase alphanumeric claim code.
-fn generate_code() -> String {
-    let mut buf = [0u8; CODE_LEN];
-    OsRng.fill_bytes(&mut buf);
-    buf.iter()
-        .map(|&b| CHARSET[(b as usize) % CHARSET.len()] as char)
-        .collect()
-}
-
 /// Insert a claim code and its associated pending account in a single transaction.
 async fn insert_pending_account(
     db: &sqlx::SqlitePool,
···
 
 #[cfg(test)]
 mod tests {
-    use std::sync::Arc;
-
     use axum::{
         body::Body,
         http::{Request, StatusCode},
     };
     use tower::ServiceExt;
 
-    use crate::app::{app, test_state, AppState};
+    use crate::app::{app, test_state};
+    use crate::routes::test_utils::test_state_with_admin_token;
 
     // ── Helpers ───────────────────────────────────────────────────────────────
-
-    async fn test_state_with_admin_token() -> AppState {
-        let base = test_state().await;
-        let mut config = (*base.config).clone();
-        config.admin_token = Some("test-admin-token".to_string());
-        AppState {
-            config: Arc::new(config),
-            db: base.db,
-        }
-    }
 
     fn post_create_account(body: &str, bearer: Option<&str>) -> Request<Body> {
         let mut builder = Request::builder()
···
 
     #[tokio::test]
     async fn duplicate_handle_in_handles_returns_409() {
-        // handle_in_handles query (line ~129) coverage
+        // handle_in_handles query coverage
         let state = test_state_with_admin_token().await;
 
         // Seed a fully-provisioned account with an active handle.

crates/relay/src/routes/create_signing_key.rs

···
 // pattern: Imperative Shell
 //
-// Gathers: Bearer token from Authorization header, JSON request body, config, DB pool
+// Gathers: admin Bearer token (Authorization header), JSON request body, config, DB pool
 // Processes: auth check → algorithm check → master key check → key generation → encryption → DB insert
 // Returns: JSON { key_id, public_key, algorithm } on success; ApiError on all failure paths
 
 use axum::{extract::State, http::HeaderMap, response::Json};
 use serde::{Deserialize, Serialize};
-use subtle::ConstantTimeEq;
 
 use common::{ApiError, ErrorCode};
 
 use crate::app::AppState;
+use crate::routes::auth::require_admin_token;
 
 #[derive(Deserialize)]
 #[serde(rename_all = "lowercase")]
···
 ) -> Result<Json<CreateSigningKeyResponse>, ApiError> {
     // --- Auth: require matching Bearer token ---
     // Check this first so unauthenticated callers cannot probe server configuration.
-    let expected_token = state
-        .config
-        .admin_token
-        .as_deref()
-        .ok_or_else(|| ApiError::new(ErrorCode::Unauthorized, "admin token not configured"))?;
-
-    let auth_value = headers
-        .get(axum::http::header::AUTHORIZATION)
-        .and_then(|v| v.to_str().ok())
-        .unwrap_or("");
-
-    let provided_token = auth_value.strip_prefix("Bearer ").ok_or_else(|| {
-        ApiError::new(
-            ErrorCode::Unauthorized,
-            "missing or invalid Authorization header",
-        )
-    })?;
-
-    if provided_token
-        .as_bytes()
-        .ct_eq(expected_token.as_bytes())
-        .unwrap_u8()
-        != 1
-    {
-        return Err(ApiError::new(
-            ErrorCode::Unauthorized,
-            "invalid admin token",
-        ));
-    }
+    require_admin_token(&headers, &state)?;
 
     // --- Master key: return 503 if not configured ---
     let master_key: &[u8; 32] = state

crates/relay/src/routes/mod.rs

···
+pub mod auth;
 pub mod claim_codes;
 pub mod create_account;
 pub mod create_signing_key;
 pub mod describe_server;
 pub mod health;
+
+mod code_gen;
+
+#[cfg(test)]
+pub(crate) mod test_utils;

crates/relay/src/routes/test_utils.rs

···
+use std::sync::Arc;
+
+use crate::app::{test_state, AppState};
+
+/// Minimal test state with admin_token set to `"test-admin-token"`.
+///
+/// Wraps `test_state()` and overrides the single config field that most
+/// admin-endpoint tests need. Defined once here to avoid copying the same
+/// 8-line block into every route test module.
+pub async fn test_state_with_admin_token() -> AppState {
+    let base = test_state().await;
+    let mut config = (*base.config).clone();
+    config.admin_token = Some("test-admin-token".to_string());
+    AppState {
+        config: Arc::new(config),
+        db: base.db,
+    }
+}