hecks 2.9.0 → 3.0.1

data/rust/host/src/payments.rs

@@ -0,0 +1,767 @@
+// The tenant's own link to a payment processor and what checkout does with it:
+// a business's own Stripe account, keyed by `<domain>::PaymentConnection` (see `checkout_plan`).
+
+use crate::auth;
+use crate::checkout::STRIPE_API_VERSION;
+use crate::dispatch;
+use crate::journal::LineageConfig;
+use crate::lambda_client::LambdaInvoker;
+use crate::web::{instances_for, last_refusal, respond};
+use serde_json::{json, Value};
+use std::collections::HashMap;
+use std::path::Path;
+use std::sync::Arc;
+use tokio::sync::Mutex;
+use tokio_postgres::Client;
+
+mod keystore;
+use keystore::{KeyStore, StoredDocument, StoredKeys};
+
+const CONNECTION_SLUG: &str = "payments";
+const STRIPE_API_BASE: &str = "https://api.stripe.com";
+const MODES: [&str; 2] = ["test", "live"];
+/// The reserved `account_ref` of a connection that uses the business's own
+/// Stripe account directly. It is the only kind of connection this host charges.
+pub const SELF_ACCOUNT: &str = "self";
+const DIRECT_DISPLAY_FALLBACK: &str = "Your Stripe account";
+const STRIPE_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(15);
+
+/// This deploy's payment settings, read once per request as a plain value (so a
+/// test can build one directly). Deliberately not `Debug`: it holds secret keys.
+#[derive(Clone)]
+pub struct PlatformConfig {
+    pub site_url: String,
+    /// The public origin Stripe delivers webhooks to (`PAYMENTS_WEBHOOK_BASE_URL`,
+    /// else `site_url`); the webhook the site creates points at `<this>/webhooks/stripe`.
+    pub webhook_base_url: String,
+    /// Where keys saved from the Payments page live, when this deploy has such a
+    /// store (keystore.rs); `None` means keys can only come from the environment.
+    pub store: Option<Arc<KeyStore>>,
+    /// A snapshot of what the store held when `apply_store` last ran. Empty
+    /// until then.
+    pub stored: Arc<StoredDocument>,
+    pub api_base: String,
+    /// The description Stripe shows beside the webhook endpoint this site
+    /// creates: `PAYMENTS_WEBHOOK_DESCRIPTION`, else "<HECKS_DOMAIN> website".
+    pub webhook_description: String,
+    /// The business's own Stripe keys, one pair per mode (available once both are
+    /// set). Unlike the secret, the publishable key may safely appear in a response.
+    pub direct_test_key: String,
+    pub direct_live_key: String,
+    pub direct_test_publishable_key: String,
+    pub direct_live_publishable_key: String,
+    /// The signing secret of the business's own webhook endpoint; `None` when
+    /// unset.
+    pub webhook_secret: Option<String>,
+    /// Lower-cased emails allowed to enable or disable real payments.
+    pub operators: Vec<String>,
+}
+
+/// Refuses the boot on AWS when checkout is enabled but `PAYMENTS_ACCOUNT_SECRET_ID`
+/// names no secret; off AWS, or with checkout off, the host boots as usual.
+pub fn check_boot(checkout_enabled: bool) -> Result<(), String> {
+    keystore::check_boot(checkout_enabled)
+}
+
+/// The webhook endpoint's description: the configured text when it is not
+/// blank, else "<domain> website".
+fn webhook_description(configured: Option<&str>, domain: &str) -> String {
+    match configured.map(str::trim).filter(|text| !text.is_empty()) {
+        Some(text) => text.to_string(),
+        None => format!("{domain} website"),
+    }
+}
+
+impl PlatformConfig {
+    pub fn from_env() -> Self {
+        let var = |name: &str| std::env::var(name).unwrap_or_default();
+        let site_url = std::env::var("SITE_URL").unwrap_or_else(|_| "http://localhost:4321".to_string());
+        let webhook_base_url = Some(var("PAYMENTS_WEBHOOK_BASE_URL")).filter(|url| !url.trim().is_empty()).unwrap_or_else(|| site_url.clone()).trim_end_matches('/').to_string();
+        Self {
+            site_url,
+            webhook_base_url,
+            store: keystore::default_store(),
+            stored: Arc::new(StoredDocument::default()),
+            api_base: STRIPE_API_BASE.to_string(),
+            webhook_description: webhook_description(std::env::var("PAYMENTS_WEBHOOK_DESCRIPTION").ok().as_deref(), &var("HECKS_DOMAIN")),
+            direct_test_key: var("STRIPE_ACCOUNT_TEST_KEY"),
+            direct_live_key: var("STRIPE_ACCOUNT_LIVE_KEY"),
+            direct_test_publishable_key: var("STRIPE_ACCOUNT_TEST_PUBLISHABLE_KEY"),
+            direct_live_publishable_key: var("STRIPE_ACCOUNT_LIVE_PUBLISHABLE_KEY"),
+            webhook_secret: Some(var("STRIPE_WEBHOOK_SECRET")).filter(|s| !s.is_empty()),
+            operators: var("PAYMENTS_OPERATOR_EMAILS")
+                .split(',')
+                .map(|email| email.trim().to_lowercase())
+                .filter(|email| !email.is_empty())
+                .collect(),
+        }
+    }
+
+    /// `Self::from_env()` with what the key store holds applied.
+    pub async fn load() -> Self {
+        let mut platform = Self::from_env();
+        platform.apply_store().await;
+        platform
+    }
+
+    /// Reads the key store into `stored` (from its cache when fresh); a store that
+    /// cannot be read leaves only environment keys, logged without naming any key.
+    pub async fn apply_store(&mut self) {
+        let Some(store) = self.store.clone() else { return };
+        match store.document().await {
+            Ok(document) => self.stored = document,
+            Err(e) => eprintln!("the saved payment keys could not be read, so only environment keys are used: {e}"),
+        }
+    }
+
+    /// Whether this deploy can save keys from the Payments page.
+    pub fn can_save_keys(&self) -> bool {
+        self.store.is_some()
+    }
+
+    /// Whether any real Stripe credential exists (environment or saved keys). While
+    /// one does, the public mock webhook secret must never verify anything.
+    pub fn has_real_credentials(&self) -> bool {
+        let configured = [&self.direct_test_key, &self.direct_live_key].iter().any(|key| !key.is_empty());
+        let saved = [&self.stored.test, &self.stored.live].iter().any(|keys| keys.as_ref().is_some_and(|keys| !keys.secret_key.is_empty()));
+        configured || saved
+    }
+
+    /// Every webhook signing secret this deploy accepts: the environment's, then
+    /// any saved with the business's keys.
+    pub fn webhook_secrets(&self) -> Vec<&str> {
+        self.webhook_secret.iter().map(String::as_str).chain(self.stored.webhook_secrets()).collect()
+    }
+
+    // The business's own keys for `mode`: the environment's pair when both are
+    // set, else the pair saved from the Payments page, else whatever the
+    // environment has (which then leaves the mode unavailable).
+    fn direct_pair(&self, mode: &str) -> (&str, &str) {
+        let (key, publishable) =
+            if mode == "live" { (&self.direct_live_key, &self.direct_live_publishable_key) } else { (&self.direct_test_key, &self.direct_test_publishable_key) };
+        if !key.is_empty() && !publishable.is_empty() {
+            return (key, publishable);
+        }
+        match self.stored.mode(mode) {
+            Some(saved) if !saved.secret_key.is_empty() && !saved.publishable_key.is_empty() => (&saved.secret_key, &saved.publishable_key),
+            _ => (key, publishable),
+        }
+    }
+
+    fn direct_key(&self, mode: &str) -> &str {
+        self.direct_pair(mode).0
+    }
+
+    fn direct_publishable_key(&self, mode: &str) -> &str {
+        self.direct_pair(mode).1
+    }
+
+    /// The modes the business's own account can be used in: those with both
+    /// its secret key and its publishable key, from the environment or saved.
+    pub fn direct_modes(&self) -> Vec<&'static str> {
+        MODES.into_iter().filter(|mode| !self.direct_key(mode).is_empty() && !self.direct_publishable_key(mode).is_empty()).collect()
+    }
+
+    fn is_operator(&self, email: &str) -> bool {
+        self.operators.contains(&email.to_lowercase())
+    }
+}
+
+/// The public facts a tenant's `PaymentConnection` holds.
+pub struct Connection {
+    pub status: String,
+    pub processor: String,
+    pub account_ref: String,
+    pub mode: String,
+    pub display_name: String,
+}
+
+impl Connection {
+    /// Whether this connection uses the business's own Stripe account
+    /// (`account_ref` is `SELF_ACCOUNT`), the only kind this host can charge.
+    pub fn is_direct(&self) -> bool {
+        self.account_ref == SELF_ACCOUNT
+    }
+}
+
+/// This tenant's connection, read out of the replayed instances, or `None`
+/// until an Owner has connected an account.
+pub fn connection(read: &Value, domain: &str) -> Option<Connection> {
+    let (_, state) = instances_for(read, &crate::ir::payment_connection_binding(domain).instance_prefix()).into_iter().find(|(id, _)| id == CONNECTION_SLUG)?;
+    let text = |field: &str| state.get(field).and_then(|v| v.get("value")).and_then(|v| v.as_str()).unwrap_or_default().to_string();
+    Some(Connection {
+        status: state.get("status").and_then(|v| v.as_str()).unwrap_or_default().to_string(),
+        processor: text("processor"),
+        account_ref: text("account_ref"),
+        mode: text("mode"),
+        display_name: text("display_name"),
+    })
+}
+
+/// What checkout does for one request.
+pub enum CheckoutPlan {
+    /// No connection, or one that is not enabled: the mock walkthrough.
+    Mock,
+    /// Payments are enabled: charged on the business's own account with its own
+    /// key; the guest pays in a form embedded in the site via the publishable key.
+    Stripe { api_key: String, publishable_key: String },
+    /// Payments were enabled and cannot be taken now. Registrations answer
+    /// 503; never a fallback to the mock.
+    Paused,
+}
+
+/// Decides checkout per request from the tenant's own connection, never a
+/// process-wide setting; an enabled connection this host cannot actually charge is paused too.
+pub fn checkout_plan(connection: Option<&Connection>, platform: &PlatformConfig) -> CheckoutPlan {
+    let Some(connection) = connection else { return CheckoutPlan::Mock };
+    match connection.status.as_str() {
+        "enabled" => {
+            let (key, publishable_key) = platform.direct_pair(&connection.mode);
+            if connection.processor != "stripe" || !connection.is_direct() || key.is_empty() {
+                CheckoutPlan::Paused
+            } else if publishable_key.is_empty() {
+                eprintln!(
+                    "payments are paused: the {} mode has a Stripe key but no publishable key (set STRIPE_ACCOUNT_{}_PUBLISHABLE_KEY)",
+                    connection.mode,
+                    connection.mode.to_uppercase()
+                );
+                CheckoutPlan::Paused
+            } else {
+                CheckoutPlan::Stripe { api_key: key.to_string(), publishable_key: publishable_key.to_string() }
+            }
+        }
+        "paused" => CheckoutPlan::Paused,
+        _ => CheckoutPlan::Mock,
+    }
+}
+
+async fn dispatch_on_connection(
+    which: crate::ir::ConnectionVerb,
+    facts: Value,
+    client: &Mutex<Client>,
+    wasm_path: &Path,
+    config: &LineageConfig,
+    invoker: &dyn LambdaInvoker,
+) -> anyhow::Result<dispatch::Outcome> {
+    let verb = crate::ir::payment_connection_binding(&config.domain).verb(which).to_string();
+    dispatch::handle_routed(client, wasm_path, &verb, json!(CONNECTION_SLUG), facts, None, config, invoker).await
+}
+
+/// Whether `path` belongs to the payments surface.
+pub fn owns(method: &str, path: &str) -> bool {
+    matches!(
+        (method, path),
+        ("GET", "/payments/connection")
+            | ("POST", "/payments/connection/direct")
+            | ("POST", "/payments/connection/disconnect")
+            | ("POST", "/payments/connection/enable")
+            | ("POST", "/payments/connection/disable")
+    )
+}
+
+fn json_error(status: u16, message: &str) -> Value {
+    respond(status, "application/json", &json!({"error": message}).to_string())
+}
+
+fn refusal_message(refusal: &Value) -> String {
+    ["message", "error"].iter().find_map(|key| refusal.get(*key).and_then(|v| v.as_str())).unwrap_or("Refused").to_string()
+}
+
+struct Caller {
+    owner: bool,
+    operator: bool,
+}
+
+// The person behind an account cookie, only while they still
+// have access, with what they may do here. `Err` is the JSON response.
+async fn caller(domain_ir: &Value, cookies: &HashMap<String, String>, secret: &str, client: &Mutex<Client>, platform: &PlatformConfig) -> Result<Caller, Value> {
+    let not_logged_in = || json_error(401, "not logged in");
+    let Some(email) = cookies.get(&auth::account_cookie_name()).and_then(|token| auth::verify_account_token(secret, token)) else {
+        return Err(not_logged_in());
+    };
+    match auth::active_role(client, domain_ir, &email).await {
+        Ok(Some(role)) => Ok(Caller { owner: role == "Owner", operator: platform.is_operator(&email) }),
+        Ok(None) => Err(not_logged_in()),
+        Err(e) => Err(json_error(500, &format!("members lookup failed: {e}"))),
+    }
+}
+
+fn require_owner(caller: &Caller) -> Result<(), Value> {
+    if caller.owner { Ok(()) } else { Err(json_error(403, "only an Owner can manage payments")) }
+}
+
+fn require_operator(caller: &Caller) -> Result<(), Value> {
+    if caller.operator { Ok(()) } else { Err(json_error(403, "only the platform operator can change whether payments are enabled")) }
+}
+
+// What the payments page may show: public facts and which of the business's own
+// modes have keys. Built field by field, so a credential can never appear here:
+// none is ever read into this value.
+fn connection_json(connection: Option<&Connection>, platform: &PlatformConfig, caller: &Caller) -> Value {
+    let label = connection.filter(|c| c.processor == "stripe").map(|_| "Stripe");
+    let present = |value: Option<&str>| value.filter(|s| !s.is_empty()).map(Value::from).unwrap_or(Value::Null);
+    json!({
+        "status": connection.map(|c| c.status.as_str()).unwrap_or("not_connected"),
+        "processor": present(connection.map(|c| c.processor.as_str())),
+        "label": label,
+        "account_ref": present(connection.map(|c| c.account_ref.as_str())),
+        "mode": present(connection.map(|c| c.mode.as_str())),
+        "display_name": present(connection.map(|c| c.display_name.as_str())),
+        // Always empty: no processor is connected through this host, only the
+        // business's own account is used. Pages that still read the list keep
+        // rendering.
+        "adapters": [],
+        "direct_modes": platform.direct_modes(),
+        "direct": connection.is_some_and(Connection::is_direct),
+        "can_save_keys": platform.can_save_keys(),
+        "can_manage": caller.owner,
+        "can_enable": caller.operator,
+    })
+}
+
+async fn current_connection(client: &Mutex<Client>, wasm_path: &Path, config: &LineageConfig) -> Result<Option<Connection>, Value> {
+    match dispatch::read(client, wasm_path).await {
+        Ok(read) => Ok(connection(&read, &config.domain)),
+        Err(e) => Err(json_error(500, &format!("payment connection lookup failed: {e:#}"))),
+    }
+}
+
+async fn connection_response(caller: &Caller, platform: &PlatformConfig, client: &Mutex<Client>, wasm_path: &Path, config: &LineageConfig) -> Value {
+    match current_connection(client, wasm_path, config).await {
+        Ok(connection) => {
+            respond(200, "application/json", &connection_json(connection.as_ref(), platform, caller).to_string())
+        }
+        Err(response) => response,
+    }
+}
+
+/// The `/payments/connection` routes for a caller holding the account cookie; every
+/// answer is JSON, a bad session is 401 not a redirect, and `None` means an unowned path.
+#[allow(clippy::too_many_arguments)]
+pub async fn route(
+    method: &str,
+    path: &str,
+    raw_body: &str,
+    cookies: &HashMap<String, String>,
+    secret: &str,
+    domain_ir: &Value,
+    platform: &PlatformConfig,
+    client: &Mutex<Client>,
+    wasm_path: &Path,
+    config: &LineageConfig,
+    invoker: &dyn LambdaInvoker,
+) -> Option<Value> {
+    if !owns(method, path) {
+        return None;
+    }
+    let caller = match caller(domain_ir, cookies, secret, client, platform).await {
+        Ok(caller) => caller,
+        Err(response) => return Some(response),
+    };
+    Some(match path {
+        "/payments/connection" => show(&caller, platform, client, wasm_path, config).await,
+        "/payments/connection/direct" => direct_route(&caller, raw_body, platform, client, wasm_path, config, invoker).await,
+        "/payments/connection/disconnect" => disconnect_route(&caller, platform, client, wasm_path, config, invoker).await,
+        "/payments/connection/enable" => switch_route(&caller, crate::ir::ConnectionVerb::Enable, platform, client, wasm_path, config, invoker).await,
+        _ => switch_route(&caller, crate::ir::ConnectionVerb::Disable, platform, client, wasm_path, config, invoker).await,
+    })
+}
+
+// GET: readable by an Owner or the operator, nobody else.
+async fn show(caller: &Caller, platform: &PlatformConfig, client: &Mutex<Client>, wasm_path: &Path, config: &LineageConfig) -> Value {
+    if !caller.owner && !caller.operator {
+        return json_error(403, "not permitted");
+    }
+    connection_response(caller, platform, client, wasm_path, config).await
+}
+
+fn body_field(body: &Value, key: &str) -> Result<String, Value> {
+    body.get(key).and_then(|v| v.as_str()).map(String::from).ok_or_else(|| json_error(400, &format!("missing {key}")))
+}
+
+fn parse_body(raw_body: &str) -> Result<Value, Value> {
+    serde_json::from_str(raw_body).map_err(|e| json_error(400, &format!("invalid JSON: {e}")))
+}
+
+// Records the connection an Owner just made: a first connection creates the
+// singleton, a disconnected one reconnects, a paused one resumes, and anything
+// else already has an account linked.
+async fn record_connection(
+    caller: &Caller,
+    platform: &PlatformConfig,
+    facts: Value,
+    client: &Mutex<Client>,
+    wasm_path: &Path,
+    config: &LineageConfig,
+    invoker: &dyn LambdaInvoker,
+) -> Value {
+    let existing = match current_connection(client, wasm_path, config).await {
+        Ok(existing) => existing,
+        Err(response) => return response,
+    };
+    let outcome = match existing.as_ref().map(|c| c.status.as_str()) {
+        None => {
+            let mut creation = facts;
+            creation["slug"] = json!({"value": CONNECTION_SLUG});
+            dispatch::handle_facts(client, wasm_path, &crate::ir::payment_connection_binding(&config.domain).connect, creation, None, config, invoker).await
+        }
+        Some("disconnected") => dispatch_on_connection(crate::ir::ConnectionVerb::Reconnect, facts, client, wasm_path, config, invoker).await,
+        Some("paused") => dispatch_on_connection(crate::ir::ConnectionVerb::Resume, facts, client, wasm_path, config, invoker).await,
+        Some(_) => return json_error(409, "an account is already connected — disconnect it first"),
+    };
+    match outcome {
+        Ok(outcome) if outcome.accepted => connection_response(caller, platform, client, wasm_path, config).await,
+        Ok(outcome) => json_error(422, &refusal_message(&last_refusal(&outcome.result))),
+        Err(e) => json_error(500, &format!("{e:#}")),
+    }
+}
+
+// An Owner either saves keys (`save_keys_route`) or picks a mode with keys already
+// in the environment; only public facts are stored (account ref, mode, display
+// name), and the key itself is never stored or logged.
+#[allow(clippy::too_many_arguments)]
+async fn direct_route(caller: &Caller, raw_body: &str, platform: &PlatformConfig, client: &Mutex<Client>, wasm_path: &Path, config: &LineageConfig, invoker: &dyn LambdaInvoker) -> Value {
+    if let Err(response) = require_owner(caller) {
+        return response;
+    }
+    let body = match parse_body(raw_body) {
+        Ok(body) => body,
+        Err(response) => return response,
+    };
+    // The Payments page's Save form sends the keys themselves; the other form
+    // names a mode whose keys are already in the environment.
+    if body.get("secret_key").is_some() || body.get("publishable_key").is_some() {
+        return save_keys_route(caller, &body, platform, client, wasm_path, config, invoker).await;
+    }
+    let mode = match body_field(&body, "mode") {
+        Ok(mode) => mode,
+        Err(response) => return response,
+    };
+    if !platform.direct_modes().contains(&mode.as_str()) {
+        return json_error(422, &format!("this site's own Stripe account is not set up for {mode} mode"));
+    }
+    let display_name = own_account_display_name(platform, platform.direct_key(&mode)).await;
+    let facts = json!({
+        "processor": {"value": "stripe"},
+        "account_ref": {"value": SELF_ACCOUNT},
+        "mode": {"value": mode},
+        "display_name": {"value": display_name},
+    });
+    record_connection(caller, platform, facts, client, wasm_path, config, invoker).await
+}
+
+// Not enabled: a plain disconnect. Enabled: registrations pause instead, since real
+// guests have paid through this account. Disconnecting the business's own account
+// also removes its webhook and deletes the saved keys.
+async fn disconnect_route(caller: &Caller, platform: &PlatformConfig, client: &Mutex<Client>, wasm_path: &Path, config: &LineageConfig, invoker: &dyn LambdaInvoker) -> Value {
+    if let Err(response) = require_owner(caller) {
+        return response;
+    }
+    let existing = match current_connection(client, wasm_path, config).await {
+        Ok(existing) => existing,
+        Err(response) => return response,
+    };
+    let Some(existing) = existing.filter(|c| matches!(c.status.as_str(), "connected" | "enabled")) else {
+        return json_error(409, "nothing to disconnect");
+    };
+
+    let which = if existing.status == "enabled" { crate::ir::ConnectionVerb::Suspend } else { crate::ir::ConnectionVerb::Disconnect };
+    match dispatch_on_connection(which, json!({}), client, wasm_path, config, invoker).await {
+        Ok(outcome) if outcome.accepted => {
+            if existing.is_direct() {
+                forget_saved_keys(platform, &existing.mode).await;
+            }
+            let refreshed = refreshed(platform).await;
+            connection_response(caller, &refreshed, client, wasm_path, config).await
+        }
+        Ok(outcome) => json_error(422, &refusal_message(&last_refusal(&outcome.result))),
+        Err(e) => json_error(500, &format!("{e:#}")),
+    }
+}
+
+// Enable or disable real payments: operator only.
+async fn switch_route(caller: &Caller, which: crate::ir::ConnectionVerb, platform: &PlatformConfig, client: &Mutex<Client>, wasm_path: &Path, config: &LineageConfig, invoker: &dyn LambdaInvoker) -> Value {
+    if let Err(response) = require_operator(caller) {
+        return response;
+    }
+    match current_connection(client, wasm_path, config).await {
+        Ok(Some(_)) => {}
+        Ok(None) => return json_error(409, "connect an account first"),
+        Err(response) => return response,
+    }
+    match dispatch_on_connection(which, json!({}), client, wasm_path, config, invoker).await {
+        Ok(outcome) if outcome.accepted => connection_response(caller, platform, client, wasm_path, config).await,
+        Ok(outcome) => json_error(422, &refusal_message(&last_refusal(&outcome.result))),
+        Err(e) => json_error(500, &format!("{e:#}")),
+    }
+}
+
+fn stripe_http() -> Result<reqwest::Client, String> {
+    reqwest::Client::builder().timeout(STRIPE_TIMEOUT).build().map_err(|e| e.to_string())
+}
+
+// The name of the business's own account, read with that account's own key
+// (`GET /v1/account`). Falls back to a generic label when Stripe cannot be
+// asked or has nothing better; the key is only ever sent as the bearer.
+async fn own_account_display_name(platform: &PlatformConfig, key: &str) -> String {
+    let fetch = async {
+        let response = stripe_http()?.get(format!("{}/v1/account", platform.api_base)).bearer_auth(key).send().await.map_err(|e| e.to_string())?;
+        if !response.status().is_success() {
+            return Err("account lookup refused".to_string());
+        }
+        response.json::<Value>().await.map_err(|e| e.to_string())
+    };
+    let Ok(account) = fetch.await else { return DIRECT_DISPLAY_FALLBACK.to_string() };
+    let candidates = [
+        account.get("business_profile").and_then(|p| p.get("name")),
+        account.get("settings").and_then(|s| s.get("dashboard")).and_then(|d| d.get("display_name")),
+        account.get("email"),
+    ];
+    let name = candidates.into_iter().flatten().find_map(|v| v.as_str().filter(|s| !s.is_empty())).unwrap_or(DIRECT_DISPLAY_FALLBACK).to_string();
+    name
+}
+
+const KEYS_NOT_ENABLED: &str = "saving keys is not set up on this site";
+const KEY_REFUSED: &str = "Stripe did not accept that key.";
+const STRIPE_UNREACHABLE: &str = "Could not reach Stripe. Please try again in a moment.";
+const WEBHOOK_PERMISSION: &str = "That key can't create the webhook. In Stripe, give it Webhook Endpoints → Write as well and try again.";
+const WEBHOOK_FAILED: &str = "Stripe could not set up the payment webhook. Please try again.";
+const STORE_FAILED: &str = "The keys could not be stored, so nothing was saved. Please try again.";
+const WEBHOOK_EVENTS: [&str; 3] = ["checkout.session.completed", "checkout.session.expired", "charge.refunded"];
+
+// A copy of `platform` with the key store read again, for a response that must
+// show the keys just saved or removed.
+async fn refreshed(platform: &PlatformConfig) -> PlatformConfig {
+    let mut fresh = platform.clone();
+    fresh.apply_store().await;
+    fresh
+}
+
+// The mode both keys belong to. Each message says what to fix and never quotes
+// any part of a key.
+fn keys_mode(secret_key: &str, publishable_key: &str) -> Result<&'static str, &'static str> {
+    let secret_mode = ["rk_test_", "sk_test_"]
+        .iter()
+        .any(|prefix| secret_key.starts_with(prefix))
+        .then_some("test")
+        .or_else(|| ["rk_live_", "sk_live_"].iter().any(|prefix| secret_key.starts_with(prefix)).then_some("live"))
+        .ok_or("That does not look like a Stripe restricted key. It should start with rk_test_ or rk_live_.")?;
+    let publishable_mode = if publishable_key.starts_with("pk_test_") {
+        "test"
+    } else if publishable_key.starts_with("pk_live_") {
+        "live"
+    } else {
+        return Err("That does not look like a Stripe publishable key. It should start with pk_test_ or pk_live_.");
+    };
+    if secret_mode == publishable_mode {
+        Ok(secret_mode)
+    } else {
+        Err("One key is for test mode and the other is for live mode. Use two keys from the same mode.")
+    }
+}
+
+// The business name Stripe has for an account, when it has one.
+fn business_name(account: &Value) -> Option<String> {
+    let candidates = [
+        account.get("business_profile").and_then(|p| p.get("name")),
+        account.get("settings").and_then(|s| s.get("dashboard")).and_then(|d| d.get("display_name")),
+        account.get("email"),
+    ];
+    candidates.into_iter().flatten().find_map(|v| v.as_str().filter(|s| !s.is_empty())).map(String::from)
+}
+
+// Asks Stripe whether the key works and what the business is called. A restricted
+// key that cannot read the account gets the generic name, not a refusal here:
+// creating the webhook is the real test of its permissions.
+async fn verify_key(platform: &PlatformConfig, key: &str) -> Result<String, &'static str> {
+    let response = stripe_http()
+        .map_err(|_| STRIPE_UNREACHABLE)?
+        .get(format!("{}/v1/account", platform.api_base))
+        .bearer_auth(key)
+        .header("Stripe-Version", STRIPE_API_VERSION)
+        .send()
+        .await
+        .map_err(|_| STRIPE_UNREACHABLE)?;
+    let status = response.status();
+    if status.as_u16() == 401 {
+        return Err(KEY_REFUSED);
+    }
+    if !status.is_success() {
+        return Ok(DIRECT_DISPLAY_FALLBACK.to_string());
+    }
+    let account = response.json::<Value>().await.unwrap_or(Value::Null);
+    Ok(business_name(&account).unwrap_or_else(|| DIRECT_DISPLAY_FALLBACK.to_string()))
+}
+
+enum WebhookError {
+    /// The key is not allowed to create webhook endpoints.
+    Permission,
+    /// Anything else: Stripe down, refusing the request, or answering oddly.
+    Other,
+}
+
+// Creates the webhook endpoint in the business's own Stripe account and returns
+// its id and signing secret. Stripe shows the signing secret only in this
+// answer, so it is captured here and nowhere else. Only the status is logged.
+async fn create_webhook(platform: &PlatformConfig, key: &str) -> Result<(String, String), WebhookError> {
+    let url = format!("{}/webhooks/stripe", platform.webhook_base_url);
+    let mut params: Vec<(String, String)> = vec![("url".into(), url), ("description".into(), platform.webhook_description.clone())];
+    params.extend(WEBHOOK_EVENTS.iter().enumerate().map(|(index, event)| (format!("enabled_events[{index}]"), event.to_string())));
+    let response = stripe_http()
+        .map_err(|_| WebhookError::Other)?
+        .post(format!("{}/v1/webhook_endpoints", platform.api_base))
+        .bearer_auth(key)
+        .header("Stripe-Version", STRIPE_API_VERSION)
+        .form(&params)
+        .send()
+        .await
+        .map_err(|_| WebhookError::Other)?;
+    let status = response.status();
+    if matches!(status.as_u16(), 401 | 403) {
+        return Err(WebhookError::Permission);
+    }
+    if !status.is_success() {
+        eprintln!("Stripe refused to create the payment webhook ({status})");
+        return Err(WebhookError::Other);
+    }
+    let body: Value = response.json().await.map_err(|_| WebhookError::Other)?;
+    let text = |field: &str| body.get(field).and_then(|v| v.as_str()).filter(|s| !s.is_empty()).map(String::from);
+    match (text("id"), text("secret")) {
+        (Some(id), Some(secret)) => Ok((id, secret)),
+        _ => Err(WebhookError::Other),
+    }
+}
+
+// Removes a webhook endpoint from the business's Stripe account, best effort:
+// the answer says whether Stripe confirmed it, and nothing else is reported.
+async fn delete_webhook(platform: &PlatformConfig, key: &str, endpoint_id: &str) -> bool {
+    let Ok(http) = stripe_http() else { return false };
+    let sent = http.delete(format!("{}/v1/webhook_endpoints/{endpoint_id}", platform.api_base)).bearer_auth(key).header("Stripe-Version", STRIPE_API_VERSION).send().await;
+    matches!(sent, Ok(response) if response.status().is_success())
+}
+
+// Checks the keys, has Stripe deliver events here, and stores the keys and webhook
+// secret before recording the connection; saving again in place replaces both.
+// Nothing here answers with, logs, or errors with a key.
+#[allow(clippy::too_many_arguments)]
+async fn save_keys_route(caller: &Caller, body: &Value, platform: &PlatformConfig, client: &Mutex<Client>, wasm_path: &Path, config: &LineageConfig, invoker: &dyn LambdaInvoker) -> Value {
+    let Some(store) = platform.store.clone() else { return json_error(422, KEYS_NOT_ENABLED) };
+    let (secret_key, publishable_key) = match (body_field(body, "secret_key"), body_field(body, "publishable_key")) {
+        (Ok(secret), Ok(publishable)) => (secret.trim().to_string(), publishable.trim().to_string()),
+        (Err(response), _) | (_, Err(response)) => return response,
+    };
+    let mode = match keys_mode(&secret_key, &publishable_key) {
+        Ok(mode) => mode,
+        Err(message) => return json_error(422, message),
+    };
+    let existing = match current_connection(client, wasm_path, config).await {
+        Ok(existing) => existing,
+        Err(response) => return response,
+    };
+    let in_place = match existing.as_ref() {
+        Some(c) if matches!(c.status.as_str(), "connected" | "enabled") => {
+            if !(c.is_direct() && c.mode == mode) {
+                return json_error(409, "an account is already connected — disconnect it first");
+            }
+            true
+        }
+        _ => false,
+    };
+    let display_name = match verify_key(platform, &secret_key).await {
+        Ok(name) => name,
+        Err(message) => return json_error(422, message),
+    };
+
+    // What the last save made, to be replaced once the new webhook is safely
+    // stored: a save that fails part way must never leave the business without
+    // a working webhook.
+    let previous = store.refresh().await.ok().and_then(|document| document.mode(mode).cloned()).filter(|old| !old.webhook_endpoint_id.is_empty());
+    let (endpoint_id, webhook_secret) = match create_webhook(platform, &secret_key).await {
+        Ok(created) => created,
+        Err(WebhookError::Permission) => return json_error(422, WEBHOOK_PERMISSION),
+        Err(WebhookError::Other) => return json_error(422, WEBHOOK_FAILED),
+    };
+    let saved = StoredKeys { secret_key: secret_key.clone(), publishable_key, webhook_secret, webhook_endpoint_id: endpoint_id.clone(), saved_at: keystore::now_timestamp() };
+    if let Err(e) = store.update(|document| document.set(mode, Some(saved))).await {
+        eprintln!("saving the payment keys failed: {e}");
+        delete_webhook(platform, &secret_key, &endpoint_id).await;
+        return json_error(500, STORE_FAILED);
+    }
+    // The new webhook and keys are stored, so the old webhook can go. Best
+    // effort: one that cannot be removed only stays in Stripe, unused.
+    if let Some(old) = previous {
+        if !delete_webhook(platform, &old.secret_key, &old.webhook_endpoint_id).await {
+            eprintln!("the previous Stripe webhook could not be removed");
+        }
+    }
+
+    let fresh = refreshed(platform).await;
+    if in_place {
+        return connection_response(caller, &fresh, client, wasm_path, config).await;
+    }
+    let facts = json!({
+        "processor": {"value": "stripe"},
+        "account_ref": {"value": SELF_ACCOUNT},
+        "mode": {"value": mode},
+        "display_name": {"value": display_name},
+    });
+    let response = record_connection(caller, &fresh, facts, client, wasm_path, config, invoker).await;
+    if response["statusCode"].as_u64() != Some(200) {
+        // The domain would not record the connection, so leave nothing behind.
+        delete_webhook(platform, &secret_key, &endpoint_id).await;
+        if store.update(|document| document.set(mode, None)).await.is_err() {
+            eprintln!("the saved payment keys could not be removed after a refused connection");
+        }
+    }
+    response
+}
+
+// After a disconnect: remove the webhook from Stripe and delete the saved keys for
+// that mode, best effort and logged without any secret. Environment keys and Stripe
+// are untouched when nothing was ever saved.
+async fn forget_saved_keys(platform: &PlatformConfig, mode: &str) {
+    let Some(store) = platform.store.clone() else { return };
+    let saved = match store.refresh().await {
+        Ok(document) => document.mode(mode).cloned(),
+        Err(e) => {
+            eprintln!("the saved payment keys could not be read for removal: {e}");
+            return;
+        }
+    };
+    let Some(saved) = saved else { return };
+    if !saved.webhook_endpoint_id.is_empty() && !delete_webhook(platform, &saved.secret_key, &saved.webhook_endpoint_id).await {
+        eprintln!("the Stripe webhook could not be removed from the business's account");
+    }
+    if let Err(e) = store.update(|document| document.set(mode, None)).await {
+        eprintln!("the saved payment keys could not be deleted: {e}");
+    }
+}
+
+/// Settings with nothing configured: no keys, no webhook secret, and a Stripe
+/// base URL that nothing listens on. What a mock deploy looks like.
+#[cfg(test)]
+pub(crate) fn test_platform() -> PlatformConfig {
+    PlatformConfig {
+        site_url: "http://localhost:4321".to_string(),
+        webhook_base_url: "http://localhost:4321".to_string(),
+        store: None,
+        stored: Arc::new(StoredDocument::default()),
+        api_base: "http://127.0.0.1:9".to_string(),
+        webhook_description: "Test Domain website".to_string(),
+        direct_test_key: String::new(),
+        direct_live_key: String::new(),
+        direct_test_publishable_key: String::new(),
+        direct_live_publishable_key: String::new(),
+        webhook_secret: None,
+        operators: Vec::new(),
+    }
+}
+
+/// `test_platform` with a webhook signing secret set.
+#[cfg(test)]
+pub(crate) fn test_platform_with_secret(secret: &str) -> PlatformConfig {
+    PlatformConfig { webhook_secret: Some(secret.to_string()), ..test_platform() }
+}
+
+#[cfg(test)]
+mod tests;