feat(panel): require email verification for access requests

- Make email required (not optional) for access requests, as Textile needs a confirmed contact to reply on
- Add email_verified field to track whether operator has clicked the confirm link sent by Textile
- Display verification hint in pending requests showing which email the confirm link was sent to
- Distinguish between "flagged" (blocked permanently) and "rejected" (can request again) access statuses
- Update messaging to clarify that one request covers every Swap pair on every chain, including pairs listed later
- Improve documentation on the email confirmation step and approval scope
- Add support for 4007 (VENUE_SEATS_CHANGED_CODE) close frame as a handover redirect requiring reconnect
- Update web UI copy to reflect email requirement and approval covering all pairs at once

Author: bnolens

.textile-monorepo-source

@@ -1 +1 @@
-f66d053934c70322ab67fb074f5c00495b73bda1
+79c01ad231c310d2c468009fdbc5faa5bb1684db

.textile-stitch-release-version

@@ -1 +1 @@
-0.1.234
+0.1.235

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "stitch-bot"
-version = "0.1.234"
+version = "0.1.235"
 edition = "2021"
 description = "Stitch — Textile filler-network operator bot; quotes Swap via RFQ firm quotes and optionally fills resting limit orders."
 license = "AGPL-3.0-or-later"

Cargo.toml

@@ -26,11 +26,15 @@ every new maker starts registered and dark:
 
 1. **Connect.** The bot signs `MakerEnroll` with its funding wallet and gets a
    maker id and key back. No corridor is enabled yet.
-2. **Request access.** Tell Textile who you are — email or WhatsApp. That sends
-   ops a dossier (wallet, chain, maker id, corridor, contact) with Approve and
-   Reject.
-3. **They approve**, which unflags the maker and seats every RFQ-capable
-   corridor on that chain.
+2. **Request access.** Tell Textile who you are. An email address you own is
+   required (placeholder and throwaway domains are refused); WhatsApp is
+   optional. That sends ops a dossier (wallet, chain, maker id, corridor,
+   contact) with Approve and Reject, and sends *you* a link to confirm the
+   address. Click it — the request is reviewed either way, but it shows up as
+   unverified until you do. You ask once: the same request covers every bot
+   you run on this wallet.
+3. **They approve**, which seats the maker on every RFQ corridor on every
+   chain — including pairs Textile lists later. You get an email saying so.
 4. **Check status.** Your bot picks the seat up and goes live. This does not
    rotate your key.
 
@@ -47,10 +51,10 @@ book bot is never dark in the gap. That is the whole reason to leave the ladder
    with its own funding wallet; Textile registers the maker and the panel writes
    `rfq-api.key` beside the config. You never paste an id or key.
 3. Ask Textile to seat the maker. Newer panels have a **Request access** form
-   in the RFQ card — an email address or a WhatsApp number — and the card then
-   reads "Access requested". If your panel has no such form, mail
-   `contact@textilecredit.com` with the maker id from `[rfq].maker_id`, the
-   chain, and the pair.
+   in the RFQ card — an email address you own, WhatsApp optional — and the
+   card then reads "Access requested". Confirm the address from the link they
+   email you. If your panel has no such form, mail `contact@textilecredit.com`
+   with the maker id from `[rfq].maker_id`, the chain, and the pair.
 4. Wait for approval. When it lands, press **Check status** if your panel has
    it — otherwise press **Reconnect**, which re-enrolls and picks the seat up
    (it rotates the maker key; Check status does not). Either way the card goes
@@ -215,8 +219,8 @@ defaults to true) and restart.
 
 Either way, leave `[rfq]` in place. `enabled = false` parks the responder
 without discarding your maker id, so switching back is one edit rather than
-another enrollment — and it keeps your seat, which you would otherwise have to
-be approved for again.
+another enrollment. Your approval is not lost either way: it is per maker, not
+per pair, so switching back never needs a second review.
 
 Orders you already signed stay live on the book until they expire, whichever
 direction you move.

docs/migrate-book-to-rfq.md

@@ -3,7 +3,10 @@
 //! Request Textile to seat this maker, and poll until they do.
 //!
 //! Connect only registers a key. This is the last setup step: the panel
-//! posts contact details to the venue, which emails ops. Check status
+//! posts contact details to the venue, which emails ops. Asked once per
+//! maker — approval covers every RFQ corridor on every chain, including
+//! pairs listed later. The email is required and the venue mails a confirm
+//! link beside the review; the request is reviewed either way. Check status
 //! applies corridors once approved, without rotating the key.
 
 use axum::extract::{Path as UrlPath, State};
@@ -51,6 +54,37 @@ struct AccessStatusResponse {
     corridors: Vec<String>,
     #[serde(default)]
     corridor_pairs: Vec<EnrollCorridorPair>,
+    #[serde(default)]
+    contact_email: Option<String>,
+    /// False until the operator clicks the confirm link. Older venues omit
+    /// it, and "omitted" must not read as "not confirmed".
+    #[serde(default)]
+    email_verified: Option<bool>,
+}
+
+/// What the venue says back to a filed request.
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct AccessRequestResponse {
+    #[serde(default)]
+    contact_email: Option<String>,
+    #[serde(default)]
+    email_verified: Option<bool>,
+}
+
+/// The line under "Request sent" / "still pending": only nags about the
+/// confirm link while the venue actually says it is unconfirmed.
+fn verify_hint(contact_email: Option<&str>, email_verified: Option<bool>) -> String {
+    match (email_verified, contact_email) {
+        (Some(false), Some(email)) => format!(
+            " Confirm your email: we sent a link to {email}. Request access again to resend it."
+        ),
+        (Some(false), None) => {
+            " Confirm your email: we sent you a link. Request access again to resend it."
+                .to_string()
+        }
+        _ => String::new(),
+    }
 }
 
 /// Body for POST /v2/maker/access-request. The form leaves most of these
@@ -75,13 +109,13 @@ fn filled(value: Option<&str>) -> Option<&str> {
 }
 
 /// Email is the channel Textile answers a review on, so it is the required
-/// one. WhatsApp is a bonus number for them to ping.
+/// one — and the one they ask you to confirm. WhatsApp is a bonus number.
 fn require_email(email: Option<&str>) -> Result<(), ApiError> {
     if filled(email).is_some() {
         return Ok(());
     }
     Err(ApiError::bad_request(
-        "add an email address so Textile can reply to your access request — WhatsApp is optional",
+        "add an email address you own so Textile can reply to your access request — WhatsApp is optional",
     ))
 }
 
@@ -151,10 +185,25 @@ pub async fn request_access(
             .unwrap_or_else(|| format!("Textile access request failed ({status})"));
         return Err(ApiError::bad_request(message));
     }
+    let filed: AccessRequestResponse =
+        serde_json::from_str(&text).unwrap_or(AccessRequestResponse {
+            contact_email: None,
+            email_verified: None,
+        });
+    let hint = verify_hint(
+        filed
+            .contact_email
+            .as_deref()
+            .or(filled(body.contact_email.as_deref())),
+        filed.email_verified,
+    );
 
     Ok(Json(json!({
-        "message": "Request sent. Textile will review it and email you if they need anything.",
+        "message": format!(
+            "Request sent. Textile reviews it and approves you for every Swap pair at once.{hint}"
+        ),
         "accessStatus": "PENDING",
+        "emailVerified": filed.email_verified,
     }))
     .into_response())
 }
@@ -209,19 +258,28 @@ pub async fn access_status(
     })?;
 
     if reported.access_status != "APPROVED" || reported.flagged {
-        let message = if reported.flagged || reported.access_status == "REJECTED" {
+        let message = if reported.flagged {
             format!(
-                "Textile rejected {}. You will not receive private quotes.",
+                "Textile blocked {}. You will not receive private quotes.",
+                reported.maker_slug
+            )
+        } else if reported.access_status == "REJECTED" {
+            format!(
+                "Textile turned {} down. You can request access again.",
                 reported.maker_slug
             )
         } else if reported.access_status == "PENDING" {
-            "Textile still has your request. Nothing to do until they approve it.".to_string()
+            format!(
+                "Textile still has your request. Nothing to do until they approve it.{}",
+                verify_hint(reported.contact_email.as_deref(), reported.email_verified)
+            )
         } else {
             "No access request yet. Send one so Textile can review this maker.".to_string()
         };
         return Ok(Json(json!({
             "message": message,
             "accessStatus": reported.access_status,
+            "emailVerified": reported.email_verified,
             "enrollment": {
                 "makerSlug": reported.maker_slug,
                 "environment": reported.environment,
@@ -358,10 +416,7 @@ mod tests {
                             .and_then(|v| v.to_str().ok())
                             .unwrap_or("");
                         assert_eq!(auth, format!("Bearer {expect_key}"));
-                        assert!(
-                            body["contactEmail"].as_str().is_some()
-                                || body["contactWhatsapp"].as_str().is_some()
-                        );
+                        assert!(body["contactEmail"].as_str().is_some());
                         // The venue validates these as optional strings, so a
                         // blank field must be absent rather than null.
                         assert!(
@@ -372,7 +427,12 @@ mod tests {
                                 .any(Value::is_null),
                             "sent a null field: {body}"
                         );
-                        Json(json!({ "accessStatus": "PENDING", "requestId": "clreq1" }))
+                        Json(json!({
+                            "accessStatus": "PENDING",
+                            "requestId": "clreq1",
+                            "contactEmail": body["contactEmail"],
+                            "emailVerified": false,
+                        }))
                     },
                 ),
             )
@@ -564,6 +624,20 @@ mod tests {
         assert!(!body.contains("tx_live_enroll_secret"), "{body}");
         let v = Harness::parse(&body);
         assert_eq!(v["accessStatus"], "PENDING");
+        assert_eq!(v["emailVerified"], false);
+        assert!(
+            v["message"].as_str().unwrap().contains("desk@example.com"),
+            "tells them where the confirm link went: {body}"
+        );
+    }
+
+    #[test]
+    fn the_verify_hint_only_nags_while_unconfirmed() {
+        assert!(verify_hint(Some("a@b.c"), Some(false)).contains("a@b.c"));
+        assert_eq!(verify_hint(Some("a@b.c"), Some(true)), "");
+        // An older venue that does not report it must not read as unconfirmed.
+        assert_eq!(verify_hint(Some("a@b.c"), None), "");
+        assert!(verify_hint(None, Some(false)).contains("Confirm your email"));
     }
 
     #[tokio::test]

src/panel/http/access.rs

@@ -1735,6 +1735,7 @@ mod tests {
     fn only_the_redirect_codes_count_as_a_handover() {
         assert!(session::handover_close(4005), "not-the-engine redirects");
         assert!(session::handover_close(4006), "draining redirects");
+        assert!(session::handover_close(4007), "stale seats redirect");
         // Everything in 4000-4004 is the maker's problem, not the task's:
         // reconnecting instantly would hammer the venue with a credential it
         // has already rejected.

src/rfq/mod.rs

@@ -32,6 +32,10 @@ const VENUE_SUPERSEDED_CODE: u16 = 4001;
 const VENUE_NOT_ENGINE_CODE: u16 = 4005;
 /// The api task we were on is shutting down and has released the lease.
 const VENUE_DRAINING_CODE: u16 = 4006;
+/// Our seat list went stale: a corridor was listed (or left Book mode) after we
+/// authenticated. Reconnecting is what picks it up — the venue hands the
+/// corridor pairs down in SessionAccepted and nothing refreshes them in place.
+const VENUE_SEATS_CHANGED_CODE: u16 = 4007;
 
 /// The venue told us to move, and nothing is wrong with this maker.
 ///
@@ -63,9 +67,13 @@ pub struct VenueSuperseded {
     pub reason: String,
 }
 
-/// Does this close frame mean "wrong task" rather than "go away"?
+/// Does this close frame mean "reconnect now" rather than "go away"?
+///
+/// Two shapes, same policy: the task is wrong (4005/4006), or our seat list is
+/// (4007). In all three the socket and the credential are fine and the venue
+/// wants us straight back, so backing off is exactly wrong.
 pub fn handover_close(code: u16) -> bool {
-    code == VENUE_NOT_ENGINE_CODE || code == VENUE_DRAINING_CODE
+    code == VENUE_NOT_ENGINE_CODE || code == VENUE_DRAINING_CODE || code == VENUE_SEATS_CHANGED_CODE
 }
 
 /// Was this failure another session taking our identity?

src/rfq/session.rs

@@ -1131,9 +1131,10 @@ function RfqCard({
         <p className="text-xs text-faint">
           Connect registers this bot&apos;s funding wallet and saves the
           credential. Textile still has to approve you before you receive
-          Swap quotes — Request access below, then Check status after they
-          do. You never paste an id or key. The venue rejects requests under 1
-          whole token so the protocol fee cannot round to zero.
+          Swap quotes — Request access below (once, for every pair), then
+          Check status after they do. You never paste an id or key. The venue
+          rejects requests under 1 whole token so the protocol fee cannot
+          round to zero.
         </p>
 
         {waiting ? (
@@ -1144,9 +1145,9 @@ function RfqCard({
               : ''}
             .{' '}
             {makerFlagged
-              ? 'Textile has flagged this maker. You will not receive Swap quotes.'
+              ? 'Textile has blocked this maker. You will not receive Swap quotes.'
               : rejected
-                ? 'Textile turned this chain down. Request access again if you want another review.'
+                ? 'Textile turned this maker down. Request access again if you want another review.'
                 : accessStatus === 'PENDING'
                   ? 'Access requested. Textile will review it. Check status after they approve you.'
                   : 'Request access so Textile can review this maker. You will not receive Swap quotes until they approve you.'}
@@ -1188,9 +1189,10 @@ function RfqCard({
           <div className="space-y-3 rounded-lg border border-line-soft p-3">
             <p className="text-sm font-bold">Request access</p>
             <p className="text-xs text-faint">
-              Textile replies about the review by email, so that one is
-              required. WhatsApp is optional — add it if you would rather they
-              ping you there.
+              One request covers every Swap pair, on every chain, including
+              pairs Textile lists later. They reply by email, so use an
+              address you own — they send a link to confirm it. WhatsApp is
+              optional.
             </p>
             <Field label="Email">
               <Input

web/src/components/SettingsForm.tsx

@@ -178,6 +178,8 @@ export interface SaveResult {
 export interface RfqAccessResult {
   message: string
   accessStatus: RfqAccessStatus
+  /** False until the confirm link is clicked; absent from older venues. */
+  emailVerified?: boolean | null
   settings?: Settings
   enrollment?: RfqEnrollment
 }