fix(channels): hand chat users the web app address when a setup ceremony can't run in chat

crates/app/ironclaw_architecture_tests/tests/reborn_dependency_boundaries.rs

@@ -822,7 +822,21 @@ fn reborn_contracts_crates_carry_a_checked_size_ceiling() {
         // host-side like `guidance_doc`'s, and nothing here schedules,
         // dispatches, or invokes anything. Count read from this test's own
         // failure message.
-        ("ironclaw_extension_contracts", 11_451),
+        // 11_451 -> 11_633 (2026-08-26, PR #7897 connect-link validation):
+        // the new `connect_link` module — one `validated_connect_link_origin`
+        // helper plus its unit tests — replaces three near-duplicate
+        // trim-and-check-non-empty implementations
+        // (`ironclaw_extension_host::channel_host::configured_origin`,
+        // `ironclaw_assistant::run_delivery::prompts::extensions_page_link`,
+        // `ironclaw_extension_manager::install_guidance::personal_setup_link`)
+        // that never validated `IRONCLAW_REBORN_WEBUI_BASE_URL` was an
+        // absolute origin, so a scheme-less deployment value rendered a
+        // relative link into a customer conversation. Pure validation, no
+        // execution/persistence. Both raises are kept: this row grew twice,
+        // independently, and each delta has its own reason. 11_633 is the
+        // count read from this test's own failure message after merging main,
+        // not the two deltas added — they do not sum.
+        ("ironclaw_extension_contracts", 11_633),
         // Raised 17_501 -> 18_570 by #6831 (standardized messaging framework):
         // the growth is the `messaging` vocabulary — the StandardMessagingOp
         // enum, the 12-code error taxonomy, compiled-in canonical schema/prompt

crates/app/ironclaw_composition/src/extension_host_assembly.rs

@@ -584,6 +584,9 @@ pub(crate) fn start_channel_host(
     });
     let workflow_factory = Arc::new(ironclaw_assistant::RebornChannelWorkflowFactory::new(
         ironclaw_assistant::RebornChannelWorkflowServices {
+            // Same env read, and the same no-origin fallback, as the channel
+            // connect notice (#7887).
+            setup_link_base_url: connect_link_base_url_from_env(),
             filesystem: Arc::clone(workflow_filesystem),
             thread_service,
             turn_coordinator,

crates/app/ironclaw_composition/src/factory/test_support.rs

@@ -20,6 +20,16 @@ pub struct ChannelHostAssemblyTestWiring {
     pub turn_coordinator: Arc<dyn ironclaw_turns::TurnCoordinator>,
     pub identity: ironclaw_extension_host::channel_host::ChannelHostIdentity,
     pub run_delivery_settings: ironclaw_assistant::RunDeliverySettings,
+    /// Auth-prompt enrichment for a run parked `BlockedAuth`, forwarded
+    /// verbatim into `RunDeliveryServices.blocked_auth_prompts`. Production
+    /// always wires `None` through this test-support path (this fixture has
+    /// no `product_auth`/pairing-registry-backed source to hand it); an
+    /// integration test that needs a challenge-kind-specific unserviceable
+    /// message (`unserviceable_auth_prompt_message`'s ManualToken/DeviceLink
+    /// arms, #7897) supplies its own fake here rather than composition
+    /// growing a second real implementation just for the test.
+    pub blocked_auth_prompts:
+        Option<Arc<dyn ironclaw_product_contracts::prompt_source::BlockedAuthPromptSource>>,
 }
 
 #[allow(
@@ -359,7 +369,7 @@ impl RebornRuntimeStores {
                 auth_interaction: None,
                 identity: wiring.identity,
                 approval_context: None,
-                blocked_auth_prompts: None,
+                blocked_auth_prompts: wiring.blocked_auth_prompts,
                 auth_flow_cancel: None,
                 run_delivery_settings: wiring.run_delivery_settings,
                 admin_users,

crates/app/ironclaw_composition/src/runtime.rs

@@ -1183,6 +1183,7 @@ impl RebornRuntime {
             turn_coordinator,
             identity,
             run_delivery_settings,
+            blocked_auth_prompts,
         } = wiring;
         let attachment_filesystem = self.read_write_workspace_filesystem()?;
         let inbound_attachments: Arc<dyn ironclaw_attachments::InboundAttachmentLander> =
@@ -1234,7 +1235,7 @@ impl RebornRuntime {
                     auth_interaction: None,
                     identity,
                     approval_context: None,
-                    blocked_auth_prompts: None,
+                    blocked_auth_prompts,
                     auth_flow_cancel: None,
                     run_delivery_settings,
                     admin_users,

crates/contracts/ironclaw_extension_contracts/src/connect_link.rs

@@ -0,0 +1,162 @@
+//! Validation for the deployment-configured public web origin used to build
+//! extension connect/setup links (`/extensions`, `/chat?connect=…`) shown to
+//! chat users.
+//!
+//! The origin's source is `IRONCLAW_REBORN_WEBUI_BASE_URL`
+//! (`ironclaw_composition::extension_host_assembly::connect_link_base_url_from_env`),
+//! read independently by three call sites — the deployment-channel notice
+//! (`ironclaw_extension_host::channel_host::configured_origin`), the
+//! device-link-unavailable chat prompt
+//! (`ironclaw_assistant::run_delivery::prompts::extensions_page_link`), and
+//! the personal-account setup nudge
+//! (`ironclaw_extension_manager::install_guidance::personal_setup_link`) —
+//! that used to trim-and-check-non-empty only, never confirming the value was
+//! an absolute origin at all. A deployment misconfigured as
+//! `IRONCLAW_REBORN_WEBUI_BASE_URL=app.example.com` (no scheme) rendered the
+//! relative `app.example.com/extensions` into a customer conversation, and a
+//! value carrying a query or fragment could redirect the link away from the
+//! Extensions page. This module is the one place that decides an origin is
+//! safe to render.
+
+/// Validate `base_url` as an absolute `http`/`https` origin with no query
+/// string or fragment, and return it with any trailing slash trimmed.
+///
+/// Returns `None` for anything that is not a safely renderable origin: no
+/// value, blank/whitespace, a scheme-less (relative) value, a non-http(s)
+/// scheme, or a value carrying a `?query` or `#fragment` (either would change
+/// where the rendered link actually goes). `None` here means "ship the
+/// link-free copy" at every call site — never a startup failure. That
+/// deliberately differs from the OAuth callback consumer of the same
+/// environment variable, which fails startup on a blank value; see
+/// `connect_link_base_url_from_env`'s own doc comment for why the two
+/// consumers of one variable are allowed to disagree on how unusable costs.
+///
+/// `https://x.test/` and `https://x.test` are equivalent — the trailing
+/// slash is trimmed, not treated as part of the origin's identity.
+pub fn validated_connect_link_origin(base_url: Option<&str>) -> Option<&str> {
+    let trimmed = base_url?.trim();
+    if trimmed.is_empty() {
+        return None; // silent-ok: blank/whitespace origin means "unset"; every caller ships link-free
+    }
+
+    let scheme_end = trimmed.find("://")?; // silent-ok: no scheme means a relative value, never safe to render as a link
+    // Schemes are case-insensitive (RFC 3986 §3.1), and `.claude/rules/types.md`
+    // requires normalizing case-insensitive external values at the boundary —
+    // an operator writing `HTTPS://` means the same origin.
+    let scheme = &trimmed[..scheme_end];
+    if !scheme.eq_ignore_ascii_case("http") && !scheme.eq_ignore_ascii_case("https") {
+        return None; // silent-ok: only http(s) origins are safe to render as a clickable link
+    }
+
+    let authority = &trimmed[scheme_end + 3..];
+    if authority.contains(['?', '#']) {
+        return None; // silent-ok: a query string or fragment can redirect the link away from its intended page
+    }
+
+    let authority = authority.trim_end_matches('/');
+    if authority.is_empty() {
+        return None; // silent-ok: a scheme with no host is not a usable origin
+    }
+
+    Some(&trimmed[..scheme_end + 3 + authority.len()])
+}
+
+#[cfg(test)]
+mod tests {
+    use super::validated_connect_link_origin;
+
+    #[test]
+    fn accepts_absolute_https_origin() {
+        assert_eq!(
+            validated_connect_link_origin(Some("https://app.example.com")),
+            Some("https://app.example.com")
+        );
+    }
+
+    #[test]
+    fn accepts_an_uppercase_scheme() {
+        // Fail-safe rejection would have shipped link-free for a perfectly
+        // valid origin.
+        assert_eq!(
+            validated_connect_link_origin(Some("HTTPS://app.example.com")),
+            Some("HTTPS://app.example.com")
+        );
+    }
+
+    #[test]
+    fn accepts_absolute_http_origin() {
+        assert_eq!(
+            validated_connect_link_origin(Some("http://app.example.com")),
+            Some("http://app.example.com")
+        );
+    }
+
+    #[test]
+    fn trims_trailing_slash() {
+        assert_eq!(
+            validated_connect_link_origin(Some("https://app.example.com/")),
+            validated_connect_link_origin(Some("https://app.example.com"))
+        );
+        assert_eq!(
+            validated_connect_link_origin(Some("https://app.example.com/")),
+            Some("https://app.example.com")
+        );
+    }
+
+    #[test]
+    fn rejects_scheme_less_value() {
+        // The exact CodeRabbit-reported case: no scheme renders the RELATIVE
+        // `app.example.com/extensions` into a customer conversation.
+        assert_eq!(validated_connect_link_origin(Some("app.example.com")), None);
+    }
+
+    #[test]
+    fn rejects_non_http_scheme() {
+        assert_eq!(
+            validated_connect_link_origin(Some("ftp://app.example.com")),
+            None
+        );
+        assert_eq!(
+            validated_connect_link_origin(Some("javascript://app.example.com")),
+            None
+        );
+    }
+
+    #[test]
+    fn rejects_query_string() {
+        assert_eq!(
+            validated_connect_link_origin(Some("https://x.test/?a=1")),
+            None
+        );
+    }
+
+    #[test]
+    fn rejects_fragment() {
+        assert_eq!(
+            validated_connect_link_origin(Some("https://x.test#f")),
+            None
+        );
+    }
+
+    #[test]
+    fn rejects_query_and_fragment_together() {
+        assert_eq!(
+            validated_connect_link_origin(Some("https://x.test/?a=1#f")),
+            None
+        );
+    }
+
+    #[test]
+    fn rejects_blank_whitespace_and_none() {
+        assert_eq!(validated_connect_link_origin(None), None);
+        assert_eq!(validated_connect_link_origin(Some("")), None);
+        assert_eq!(validated_connect_link_origin(Some("   ")), None);
+        assert_eq!(validated_connect_link_origin(Some("/")), None);
+    }
+
+    #[test]
+    fn rejects_scheme_with_no_host() {
+        assert_eq!(validated_connect_link_origin(Some("https://")), None);
+        assert_eq!(validated_connect_link_origin(Some("https:///")), None);
+    }
+}

crates/contracts/ironclaw_extension_contracts/src/device_link.rs

@@ -135,6 +135,18 @@ pub enum DeviceLinkErrorCode {
     VendorUnavailable,
     /// Host-side custody failed (see [`LinkedSessionError`]).
     CustodyFailed,
+    /// The deployment has not finished configuring what this ceremony needs
+    /// — an operator must supply a credential or setting before ANY user can
+    /// link.
+    ///
+    /// Distinct from [`Self::Internal`], whose contract reserves it for
+    /// genuinely unclassifiable failures: this one is precisely classifiable
+    /// and precisely remediable, just not by the person looking at the card.
+    /// Distinct from [`Self::AccountUnavailable`] in the direction that
+    /// matters — nothing is wrong with the account, so copy that blames it
+    /// sends the user to debug something that is not broken (#7887 follow-up).
+    /// Terminal for the user; retrying changes nothing until an operator acts.
+    NotConfigured,
     /// Anything else. Reserved for genuinely unclassifiable failures.
     Internal,
 }
@@ -529,6 +541,11 @@ pub enum DeviceLinkError {
     /// Custody failed; the link cannot be made durable.
     #[error("device-link custody failed")]
     Custody(#[from] LinkedSessionError),
+    /// The deployment has not configured what this ceremony needs. `reason`
+    /// names the missing setting so an operator can act on it; the user
+    /// cannot.
+    #[error("device-link is not configured on this deployment: {reason}")]
+    NotConfigured { reason: &'static str },
     /// The adapter failed for a reason the run cannot recover from.
     #[error("device-link adapter failed: {reason}")]
     Internal { reason: &'static str },
@@ -542,6 +559,7 @@ impl DeviceLinkError {
             Self::InvalidInput { .. } | Self::InvalidStep { .. } => {
                 DeviceLinkErrorCode::InvalidInput
             }
+            Self::NotConfigured { .. } => DeviceLinkErrorCode::NotConfigured,
             Self::UnsupportedMode { .. } | Self::Internal { .. } => DeviceLinkErrorCode::Internal,
             Self::Vendor { code, .. } => *code,
             Self::Custody(_) => DeviceLinkErrorCode::CustodyFailed,
@@ -552,9 +570,10 @@ impl DeviceLinkError {
     pub fn restartable(&self) -> bool {
         match self {
             Self::UnknownFlow | Self::InvalidInput { .. } => true,
-            Self::InvalidStep { .. } | Self::UnsupportedMode { .. } | Self::Internal { .. } => {
-                false
-            }
+            Self::InvalidStep { .. }
+            | Self::UnsupportedMode { .. }
+            | Self::NotConfigured { .. }
+            | Self::Internal { .. } => false,
             Self::Vendor { restartable, .. } => *restartable,
             Self::Custody(_) => false,
         }

crates/contracts/ironclaw_extension_contracts/src/device_link/tests.rs

@@ -472,3 +472,42 @@ fn context_debug_reports_identity_only() {
     assert!(rendered.contains("example"), "{rendered}");
     assert!(!rendered.contains("sensitive-config-value"), "{rendered}");
 }
+
+/// #7887 follow-up: a deployment-configuration gap must not travel as
+/// `Internal`, and must not be renderable as "this account cannot be linked".
+///
+/// The account is fine; an operator has not finished setup. `Internal`'s own
+/// contract reserves it for "genuinely unclassifiable failures", and this one
+/// names the missing settings exactly — so it was both misclassified and,
+/// downstream, rendered as a false claim about the user's account.
+#[test]
+fn a_configuration_gap_is_classified_apart_from_an_unclassifiable_failure() {
+    let not_configured = DeviceLinkError::NotConfigured {
+        reason: "the deployment has not configured its MTProto application identity",
+    };
+
+    assert_eq!(not_configured.code(), DeviceLinkErrorCode::NotConfigured);
+    assert_ne!(
+        not_configured.code(),
+        DeviceLinkErrorCode::Internal,
+        "a precisely remediable gap is not an unclassifiable failure"
+    );
+    assert_ne!(
+        not_configured.code(),
+        DeviceLinkErrorCode::AccountUnavailable,
+        "nothing is wrong with the user's account"
+    );
+    // Terminal for the user: a restart cannot help until an operator acts.
+    assert!(!not_configured.restartable());
+    // The wire form the card branches on to pick its terminal copy.
+    assert_eq!(
+        serde_json::to_string(&DeviceLinkErrorCode::NotConfigured).expect("serialize"),
+        "\"not_configured\""
+    );
+    // The reason names the missing settings so an operator can act on it.
+    assert!(
+        not_configured
+            .to_string()
+            .contains("MTProto application identity")
+    );
+}

crates/contracts/ironclaw_extension_contracts/src/lib.rs

@@ -42,6 +42,7 @@ pub mod auth_prompt;
 pub mod channel;
 pub mod channel_adapter;
 pub mod channel_identity;
+pub mod connect_link;
 pub mod device_link;
 pub mod egress;
 pub mod extension;

crates/domains/ironclaw_auth/src/product_auth/device_link/driver.rs

@@ -814,6 +814,9 @@ fn auth_error_for(code: DeviceLinkErrorCode) -> AuthErrorCode {
         | DeviceLinkErrorCode::VendorUnavailable
         | DeviceLinkErrorCode::CustodyFailed
         | DeviceLinkErrorCode::Internal => AuthErrorCode::BackendUnavailable,
+        // An operator-configuration gap, not a flaky backend: `BackendUnavailable`
+        // would tell the caller to retry a service that is perfectly healthy.
+        DeviceLinkErrorCode::NotConfigured => AuthErrorCode::MalformedConfig,
     }
 }