@cat-factory/app 0.260.1 → 0.261.1

package/app/components/settings/McpAuthorizeScreen.vue

@@ -0,0 +1,262 @@
+<script setup lang="ts">
+import { computed, onMounted, ref } from 'vue'
+import {
+  MCP_AUTHORIZATION_REQUEST_INVALID,
+  PUBLIC_API_SCOPES,
+  type PublicApiScope,
+} from '@cat-factory/contracts'
+import { apiErrorEnvelope, apiErrorReason } from '~/composables/api/errors'
+
+// The consent screen an MCP host's authorization request lands on
+// (`/mcp-authorize?request=…`), reached by a redirect from `GET /oauth/authorize`.
+//
+// A page in the APP rather than a screen the backend renders, and that is the security shape of
+// this flow: the authorization endpoint is a top-level navigation a third party triggers, carrying
+// no bearer token, so a screen served there could never say WHO is approving. Here the session is
+// the app's own, and the two calls this page makes are ordinary gated API where the board choice
+// and its `secrets.manage` check actually run.
+//
+// Not a public route: an expired session renders the login screen on this same URL, and once the
+// person signs in the query string is still here and the flow continues (`postSignInUrl`, which
+// LoginScreen reloads to, exists to keep it). That is correct rather than a gap, and it is also how
+// an SSO deployment gets its identity provider into a flow that otherwise has no idea who anyone
+// is.
+
+const api = useApi()
+const { t } = useI18n()
+
+type Screen = 'loading' | 'deciding' | 'submitting' | 'failed'
+
+const screen = ref<Screen>('loading')
+const detail = ref<string | null>(null)
+/**
+ * A refusal that did NOT consume the request, shown beside the choices rather than instead of
+ * them. See `decide`: the two failures are answered differently because only one of them ends the
+ * flow.
+ */
+const decisionError = ref<string | null>(null)
+const clientName = ref('')
+const redirectOrigin = ref('')
+const workspaces = ref<{ label: string; value: string }[]>([])
+const workspaceId = ref<string | undefined>(undefined)
+/**
+ * Starts at the FLOOR of the ladder and is replaced by the server's `defaultScope` once the request
+ * resolves. The screen never preselects from the host's own ask: an unauthenticated registration
+ * can name any scope, so the server clamps it (`consentDefaultScope`) and this page renders what it
+ * was given. Least privilege before that answer arrives, in case a render ever beats it.
+ */
+const scope = ref<PublicApiScope>('read')
+/** What the host asked for, when the server preselected something else. Shown, never applied. */
+const requestedScope = ref<PublicApiScope | null>(null)
+
+const sealedRequest = computed(() =>
+  typeof window === 'undefined'
+    ? ''
+    : (new URLSearchParams(window.location.search).get('request') ?? ''),
+)
+
+/**
+ * The ladder, as choices. Every rung is offered rather than a curated subset: the rungs are what
+ * the surface itself enforces, and hiding one would leave a host that genuinely needs it unable to
+ * be granted it from the screen built for granting.
+ */
+const scopeItems = computed(() =>
+  PUBLIC_API_SCOPES.map((value) => ({
+    value,
+    label: t(`mcpAuthorize.scope.${value}.label`),
+    description: t(`mcpAuthorize.scope.${value}.description`),
+  })),
+)
+
+onMounted(async () => {
+  if (!sealedRequest.value) {
+    screen.value = 'failed'
+    detail.value = t('mcpAuthorize.error.noRequest')
+    return
+  }
+  try {
+    const [request, boards] = await Promise.all([
+      api.describeMcpAuthorization(sealedRequest.value),
+      api.listWorkspaces(),
+    ])
+    clientName.value = request.clientName
+    redirectOrigin.value = request.redirectOrigin
+    scope.value = request.defaultScope
+    // Only worth saying when the two differ: identical values would be a line telling a person
+    // that the thing in front of them is the thing in front of them.
+    requestedScope.value =
+      request.requestedScope && request.requestedScope !== request.defaultScope
+        ? request.requestedScope
+        : null
+    workspaces.value = boards.map((board) => ({ label: board.name, value: board.id }))
+    workspaceId.value = workspaces.value[0]?.value
+    screen.value = 'deciding'
+  } catch (e) {
+    // Terminal whatever the cause: with no request to describe there is nothing to decide, and the
+    // person is told to start again from the host, which is the only place a new one comes from.
+    screen.value = 'failed'
+    detail.value = apiErrorEnvelope(e)?.message ?? t('mcpAuthorize.error.expired')
+  }
+})
+
+async function decide(decision: 'approve' | 'deny') {
+  if (decision === 'approve' && !workspaceId.value) return
+  screen.value = 'submitting'
+  decisionError.value = null
+  try {
+    const result = await api.decideMcpAuthorization(
+      decision === 'approve'
+        ? {
+            decision,
+            request: sealedRequest.value,
+            workspaceId: workspaceId.value as string,
+            scope: scope.value,
+          }
+        : { decision, request: sealedRequest.value },
+    )
+    // A full navigation, never a router push: the destination is the HOST's own callback, which is
+    // waiting for a browser to arrive at it with the code on the query string.
+    if (typeof window !== 'undefined') window.location.assign(result.redirectTo)
+  } catch (e) {
+    // Two outcomes, because two things can be wrong and only one of them ends the flow. The sealed
+    // request gone is TERMINAL: nothing on this page can mint another, so it says so and offers the
+    // way out. Anything else (this board is one the person cannot mint a key on, it disappeared,
+    // the deployment hiccuped) leaves the request valid and this screen the only place the decision
+    // can be made, so dropping to a dead end over it would strand a person who has a board they
+    // COULD have picked one dropdown away.
+    if (apiErrorReason(e) === MCP_AUTHORIZATION_REQUEST_INVALID) {
+      screen.value = 'failed'
+      detail.value = apiErrorEnvelope(e)?.message ?? t('mcpAuthorize.error.expired')
+      return
+    }
+    screen.value = 'deciding'
+    decisionError.value = apiErrorEnvelope(e)?.message ?? t('mcpAuthorize.error.failed')
+  }
+}
+
+function backToApp() {
+  if (typeof window !== 'undefined') window.location.assign('/')
+}
+</script>
+
+<template>
+  <div
+    class="flex min-h-screen w-screen items-center justify-center bg-slate-950 p-4 text-slate-100"
+    data-testid="mcp-authorize"
+  >
+    <div
+      class="w-full max-w-md rounded-xl border border-slate-800 bg-slate-900/80 p-8 backdrop-blur"
+    >
+      <template v-if="screen === 'loading'">
+        <UIcon name="i-lucide-loader" class="mx-auto h-10 w-10 animate-spin text-indigo-400" />
+      </template>
+
+      <template v-else-if="screen === 'failed'">
+        <UIcon name="i-lucide-alert-triangle" class="mx-auto mb-3 h-10 w-10 text-red-400" />
+        <h1
+          class="mb-1 text-center text-lg font-semibold text-white"
+          data-testid="mcp-authorize-failed"
+        >
+          {{ t('mcpAuthorize.error.title') }}
+        </h1>
+        <p class="mb-6 text-center text-sm break-words text-slate-400">{{ detail }}</p>
+        <UButton block color="neutral" variant="subtle" @click="backToApp">
+          {{ t('mcpAuthorize.back') }}
+        </UButton>
+      </template>
+
+      <template v-else>
+        <UIcon name="i-lucide-plug-zap" class="mx-auto mb-3 h-10 w-10 text-indigo-400" />
+        <h1 class="mb-1 text-center text-lg font-semibold text-white">
+          {{ t('mcpAuthorize.title', { client: clientName }) }}
+        </h1>
+        <!-- The origin is the one fact here an attacker cannot choose: it was matched against what
+             the client registered before this screen was ever reached. The name beside it is a
+             stranger's own words, so the copy presents it as a claim rather than as identity.
+             The copy reads "It says it is {client}, and …" in every locale, so BOTH holes have to
+             be filled: an unpassed `client` renders a sentence naming nobody, on the one screen
+             whose whole subject is who is asking. -->
+        <p class="mb-6 text-center text-sm text-slate-400">
+          {{ t('mcpAuthorize.subtitle', { client: clientName, origin: redirectOrigin }) }}
+        </p>
+
+        <div v-if="!workspaces.length" class="mb-6 text-center text-sm text-amber-300">
+          {{ t('mcpAuthorize.noWorkspaces') }}
+        </div>
+
+        <template v-else>
+          <UFormField :label="t('mcpAuthorize.workspace.label')" class="mb-4">
+            <USelect
+              v-model="workspaceId"
+              :items="workspaces"
+              value-key="value"
+              class="w-full"
+              data-testid="mcp-authorize-workspace"
+            />
+          </UFormField>
+
+          <UFormField
+            :label="t('mcpAuthorize.scopeLabel')"
+            :description="t('mcpAuthorize.scopeHint')"
+            :class="requestedScope ? 'mb-2' : 'mb-6'"
+          >
+            <URadioGroup
+              v-model="scope"
+              :items="scopeItems"
+              value-key="value"
+              data-testid="mcp-authorize-scope"
+            />
+          </UFormField>
+
+          <!-- Only when the host asked for something other than what is preselected. Anyone can
+               register a client and ask for `admin`, so the ask is reported as a fact ABOUT the
+               host rather than acted on: raising the grant stays a thing a person does. -->
+          <p
+            v-if="requestedScope"
+            class="mb-6 text-xs text-amber-300"
+            data-testid="mcp-authorize-requested-scope"
+          >
+            {{
+              t('mcpAuthorize.requestedScope', {
+                client: clientName,
+                scope: t(`mcpAuthorize.scope.${requestedScope}.label`),
+              })
+            }}
+          </p>
+        </template>
+
+        <p
+          v-if="decisionError"
+          class="mb-4 text-center text-sm break-words text-red-400"
+          data-testid="mcp-authorize-decision-error"
+        >
+          {{ decisionError }}
+        </p>
+
+        <div class="flex gap-2">
+          <UButton
+            block
+            color="neutral"
+            variant="subtle"
+            :disabled="screen === 'submitting'"
+            @click="decide('deny')"
+          >
+            {{ t('mcpAuthorize.deny') }}
+          </UButton>
+          <UButton
+            block
+            color="primary"
+            :loading="screen === 'submitting'"
+            :disabled="!workspaceId"
+            data-testid="mcp-authorize-approve"
+            @click="decide('approve')"
+          >
+            {{ t('mcpAuthorize.approve') }}
+          </UButton>
+        </div>
+
+        <p class="mt-4 text-center text-xs text-slate-500">{{ t('mcpAuthorize.revokeHint') }}</p>
+      </template>
+    </div>
+  </div>
+</template>

package/app/components/settings/ProviderConnectionTab.vue

@@ -15,6 +15,7 @@ import { computed, ref, toRaw, watch } from 'vue'
 import type { ConnectionTestResult } from '@cat-factory/contracts'
 import type { ProviderConfigField, ProviderConnectionKind } from '~/types/providerConnections'
 import ConnectionWarnings from '~/components/settings/ConnectionWarnings.vue'
+import ConnectionTestVerdict from '~/components/settings/ConnectionTestVerdict.vue'
 import ProvisioningLogsDrawer from '~/components/provisioning/ProvisioningLogsDrawer.vue'
 import ProviderManifestEditor from '~/components/settings/ProviderManifestEditor.vue'
 import KubernetesEnvironmentForm from '~/components/settings/KubernetesEnvironmentForm.vue'
@@ -498,7 +499,7 @@ function fieldHelp(key: string): string | undefined {
         />
       </UFormField>
 
-      <div v-if="descriptor.supportsTest" class="flex items-center gap-2">
+      <div v-if="descriptor.supportsTest" class="space-y-1.5">
         <UButton
           color="neutral"
           variant="soft"
@@ -509,12 +510,7 @@ function fieldHelp(key: string): string | undefined {
         >
           {{ t('settings.providerConnection.test.button') }}
         </UButton>
-        <span v-if="testResult && testResult.ok" class="text-xs text-emerald-400">
-          {{ testResult.message ?? t('settings.providerConnection.test.ok') }}
-        </span>
-        <span v-else-if="testResult" class="text-xs text-rose-400">
-          {{ testResult.message ?? t('settings.providerConnection.test.failed') }}
-        </span>
+        <ConnectionTestVerdict :result="testResult" />
       </div>
 
       <ConnectionWarnings :warnings="testResult?.warnings" />

package/app/components/settings/ProviderManifestEditor.vue

@@ -20,6 +20,7 @@ import { environmentManifestSchema, runnerPoolManifestSchema } from '@cat-factor
 import type { ConnectionTestResult } from '@cat-factory/contracts'
 import type { ProviderConnectionKind } from '~/types/providerConnections'
 import ConnectionWarnings from '~/components/settings/ConnectionWarnings.vue'
+import ConnectionTestVerdict from '~/components/settings/ConnectionTestVerdict.vue'
 import SecretInput from '~/components/common/SecretInput.vue'
 
 const props = defineProps<{
@@ -267,7 +268,7 @@ function onSave() {
       </UFormField>
     </div>
 
-    <div v-if="supportsTest" class="flex items-center gap-2">
+    <div v-if="supportsTest" class="space-y-1.5">
       <UButton
         color="neutral"
         variant="soft"
@@ -280,12 +281,7 @@ function onSave() {
       >
         {{ t('settings.providerConnection.test.button') }}
       </UButton>
-      <span v-if="testResult && testResult.ok" class="text-xs text-emerald-400">
-        {{ testResult.message ?? t('settings.providerConnection.test.ok') }}
-      </span>
-      <span v-else-if="testResult" class="text-xs text-rose-400">
-        {{ testResult.message ?? t('settings.providerConnection.test.failed') }}
-      </span>
+      <ConnectionTestVerdict :result="testResult" />
     </div>
 
     <ConnectionWarnings :warnings="testResult?.warnings" />

package/app/composables/api/mcpAuthorization.ts

@@ -0,0 +1,30 @@
+import {
+  decideMcpAuthorizationContract,
+  describeMcpAuthorizationContract,
+  type McpAuthorizationDecision,
+} from '@cat-factory/contracts'
+import type { ApiContext } from './context'
+
+/**
+ * The consent screen an MCP host's authorization request lands on.
+ *
+ * The mirror image of the tool-server OAuth calls beside it: those connect THIS deployment to
+ * someone else's MCP server, these let someone else's host connect to this one. Neither is
+ * workspace-prefixed, and for opposite reasons: there the board is sealed into the vendor's state,
+ * here it is what the person on the screen is choosing.
+ *
+ * Both are POSTs, the read included. The sealed request is a value the page carries rather than an
+ * id it looks up, and a query string would write it into browser history and every log in between.
+ */
+export function mcpAuthorizationApi({ send }: ApiContext) {
+  return {
+    describeMcpAuthorization: (request: string) =>
+      send(describeMcpAuthorizationContract, { body: { request } }),
+
+    // Answers with WHERE to send the browser, rather than redirecting: a 302 on a `fetch` is
+    // followed by the browser without this page seeing it, which would deliver the host's callback
+    // an XHR instead of the navigation it is waiting for.
+    decideMcpAuthorization: (body: McpAuthorizationDecision) =>
+      send(decideMcpAuthorizationContract, { body }),
+  }
+}

package/app/composables/useApi.ts

@@ -35,6 +35,7 @@ import { modelsApi } from './api/models'
 import { notificationsApi } from './api/notifications'
 import { packageRegistriesApi } from './api/packageRegistries'
 import { capabilityCredentialsApi } from './api/capabilityCredentials'
+import { mcpAuthorizationApi } from './api/mcpAuthorization'
 import { toolServersApi } from './api/toolServers'
 import { preflightsApi } from './api/preflights'
 import { presetsApi } from './api/presets'
@@ -161,6 +162,7 @@ export function useApi() {
     ...testSecretsApi(ctx),
     ...packageRegistriesApi(ctx),
     ...capabilityCredentialsApi(ctx),
+    ...mcpAuthorizationApi(ctx),
     ...toolServersApi(ctx),
     ...previewApi(ctx),
     ...environmentsApi(ctx),

package/app/composables/useServiceAccountTokenProblem.ts

@@ -0,0 +1,52 @@
+import { computed, type ComputedRef, type Ref } from 'vue'
+import {
+  classifyServiceAccountToken,
+  isFatalServiceAccountTokenProblem,
+  type ServiceAccountTokenProblem,
+} from '@cat-factory/contracts'
+
+// Inline validation of a pasted Kubernetes ServiceAccount token, shared by the two kube connect
+// forms so they cannot drift on what a bad paste is or on what to say about it.
+//
+// The rule itself is in `@cat-factory/contracts` because the backend enforces the same one (see
+// `KubernetesApiClient`), and this is the SPA half of the split CLAUDE.md prescribes: the backend
+// emits a machine-readable code, the SPA owns the translated prose. So the map below is the one
+// place a problem code becomes copy.
+
+/**
+ * The message key per problem, as an exhaustive `Record`: a code added to the contract union fails
+ * the typecheck here until it has copy, rather than rendering as a silently missing hint. The keys
+ * are literals for the same reason they are elsewhere in the SPA (an assembled key is invisible to
+ * the typed-message-key check), and they sit under the shared `providerConnection` namespace
+ * because both the per-type engine form and the legacy single-connection form show them.
+ */
+const MESSAGE_KEYS: Record<ServiceAccountTokenProblem, string> = {
+  whitespace: 'settings.providerConnection.serviceAccountToken.whitespace',
+  'base64-encoded': 'settings.providerConnection.serviceAccountToken.base64Encoded',
+  'not-a-jwt': 'settings.providerConnection.serviceAccountToken.notAJwt',
+}
+
+export interface ServiceAccountTokenCheck {
+  /** The problem code, or null when the value looks fine (and when it is empty). */
+  problem: ComputedRef<ServiceAccountTokenProblem | null>
+  /**
+   * Whether the problem should BLOCK Test and Save. True only for the impossible case (whitespace
+   * inside the token), never for the merely-suspicious shapes: a `--token-auth-file` apiserver
+   * accepts an arbitrary static bearer token, and a check that cannot be sure must not be the
+   * thing that stops a legitimate cluster being configured.
+   */
+  blocking: ComputedRef<boolean>
+  /** The translated hint to render under the field, or '' when there is nothing to say. */
+  message: ComputedRef<string>
+}
+
+/** Classify the live value of a token field and render the verdict as translated copy. */
+export function useServiceAccountTokenProblem(token: Ref<string>): ServiceAccountTokenCheck {
+  const { t } = useI18n()
+  const problem = computed(() => classifyServiceAccountToken(token.value))
+  return {
+    problem,
+    blocking: computed(() => !!problem.value && isFatalServiceAccountTokenProblem(problem.value)),
+    message: computed(() => (problem.value ? t(MESSAGE_KEYS[problem.value]) : '')),
+  }
+}

package/app/pages/mcp-authorize.vue

@@ -0,0 +1,7 @@
+<script setup lang="ts">
+import McpAuthorizeScreen from '~/components/settings/McpAuthorizeScreen.vue'
+</script>
+
+<template>
+  <McpAuthorizeScreen />
+</template>

package/app/stores/auth/session.ts

@@ -1,5 +1,6 @@
 import type { Ref } from 'vue'
 import type { AuthUser } from '~/types/domain'
+import { postSignInUrl } from '~/utils/postSignIn'
 
 /**
  * Shared reactive state + injected dependencies the auth-store sign-in factory closes over.
@@ -24,9 +25,20 @@ export interface AuthSessionContext {
 export function createAuthSessionActions(ctx: AuthSessionContext) {
   const { api, apiBase, token, user, autoLoginProvider } = ctx
 
-  /** Build a post-login redirect back to the current page, with an optional invite. */
+  /**
+   * Build a post-login redirect back to the current page, with an optional invite.
+   *
+   * "The current page" includes its QUERY STRING, through the same `postSignInUrl` the credential
+   * forms reload to, so the round-trip through an identity provider lands where the person started
+   * rather than one level up. A flow that carries its whole subject there (`/mcp-authorize?request=`)
+   * otherwise comes back from the IdP to a page that no longer knows what it was asked, and this is
+   * the path an SSO deployment takes for EVERY sign-in, not an unusual one.
+   *
+   * The `invite` is dropped from the returned-to URL by that helper and named as its own parameter
+   * here, which is the same token travelling as itself rather than twice.
+   */
   function redirectTarget(invite?: string): string {
-    const here = window.location.origin + window.location.pathname
+    const here = window.location.origin + postSignInUrl(window.location)
     const params = new URLSearchParams({ redirect: here })
     if (invite) params.set('invite', invite)
     return params.toString()

package/app/stores/ui/k3sDeepLink.spec.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { createUiModals } from '~/stores/ui/modals'
+
+/**
+ * The `cat-factory k3s` CLI hand-off (`?infraSetup=local-k3s&…`), driven through the modals slice
+ * directly (plain refs/functions, no Pinia) exactly as the overlay-host slice tests do.
+ *
+ * What is worth pinning here is the ARRIVAL, not the parsing: the CLI's whole promise is that the
+ * operator lands on the one form it just filled in, and both halves of that (the tab AND the
+ * section anchor within it) are set in this one function. The prefill is asserted alongside
+ * because the deep link is the only thing that ever sets it.
+ */
+function openWith(search: string): void {
+  window.history.replaceState(null, '', `/${search}`)
+}
+
+const K3S_LINK =
+  '?infraSetup=local-k3s&label=Local+k3s&apiServerUrl=https%3A%2F%2F127.0.0.1%3A6443' +
+  '&namespaceTemplate=cf-env-%7B%7BpullNumber%7D%7D&hostTemplate=%7B%7Bbranch%7D%7D.127.0.0.1.nip.io' +
+  '&insecureSkipTlsVerify=1'
+
+describe('consumeK3sSetupDeepLink', () => {
+  beforeEach(() => {
+    openWith('')
+  })
+
+  it('opens the Test-environments tab ANCHORED on the Kubernetes section', () => {
+    const ui = createUiModals()
+    openWith(K3S_LINK)
+    ui.consumeK3sSetupDeepLink()
+
+    expect(ui.infrastructureOpen.value).toBe(true)
+    expect(ui.infrastructureTab.value).toBe('environment')
+    // The tab opens on the default-provision picker, so without this the operator lands above
+    // the form the CLI just described and has to scroll to find it.
+    expect(ui.infrastructureScrollTarget.value).toBe('kubernetes')
+    expect(ui.k3sSetupPrefill.value).toEqual({
+      label: 'Local k3s',
+      apiServerUrl: 'https://127.0.0.1:6443',
+      namespaceTemplate: 'cf-env-{{pullNumber}}',
+      hostTemplate: '{{branch}}.127.0.0.1.nip.io',
+      insecureSkipTlsVerify: true,
+    })
+  })
+
+  it('strips the params so a reload neither re-opens the window nor re-anchors it', () => {
+    const ui = createUiModals()
+    openWith(K3S_LINK)
+    ui.consumeK3sSetupDeepLink()
+    expect(window.location.search).toBe('')
+
+    const reloaded = createUiModals()
+    reloaded.consumeK3sSetupDeepLink()
+    expect(reloaded.infrastructureOpen.value).toBe(false)
+    expect(reloaded.infrastructureScrollTarget.value).toBeNull()
+  })
+
+  it('drops an UNCONSUMED anchor on close, so the next plain open does not scroll', () => {
+    // The panel clears the target once it has scrolled. Closing before it rendered (the window
+    // was dismissed, or the infra probe never resolved) must not leave the anchor armed.
+    const ui = createUiModals()
+    openWith(K3S_LINK)
+    ui.consumeK3sSetupDeepLink()
+    ui.closeProviderConnection()
+
+    expect(ui.infrastructureScrollTarget.value).toBeNull()
+    expect(ui.k3sSetupPrefill.value).toBeNull()
+  })
+
+  it('is a no-op for an unrelated query string', () => {
+    const ui = createUiModals()
+    openWith('?settings=default-test-env')
+    ui.consumeK3sSetupDeepLink()
+
+    expect(ui.infrastructureOpen.value).toBe(false)
+    expect(ui.infrastructureScrollTarget.value).toBeNull()
+    expect(window.location.search).toBe('?settings=default-test-env')
+  })
+})

package/app/stores/ui/modals.ts

@@ -1,6 +1,10 @@
 import { ref } from 'vue'
 import type { DocumentSourceKind, InfraSetupArea, TaskSourceKind } from '~/types/domain'
-import type { InfrastructureTab, ProviderConnectionKind } from '~/types/providerConnections'
+import type {
+  InfrastructureScrollTarget,
+  InfrastructureTab,
+  ProviderConnectionKind,
+} from '~/types/providerConnections'
 import type { PendingContext } from '~/composables/useContextLinking'
 import {
   infraSetupDismissalKey,
@@ -737,6 +741,13 @@ function createInfraModals(resetHubReturn: ResetHubReturn) {
   // `local-k3s` connection from it; the ServiceAccount token is deliberately NOT in the link (a
   // secret in a URL leaks into history/logs), so the user still pastes it before Test → Save.
   const k3sSetupPrefill = ref<K3sSetupPrefill | null>(null)
+  // A one-shot deep-link anchor into a SECTION of the open tab, mirroring
+  // `accountSettingsScrollTarget`. The Test-environments tab opens on the default-provision
+  // picker and the Compose wizard, with the per-type handler sections between them, so landing an
+  // operator at the top of it after a `cat-factory k3s` hand-off leaves them scrolling to find the
+  // very form the CLI just filled in. The owning panel scrolls the section into view once and
+  // then calls `clearInfrastructureScrollTarget`, so a later plain open doesn't re-scroll.
+  const infrastructureScrollTarget = ref<InfrastructureScrollTarget | null>(null)
   // Environment setup wizard (shared-stacks slice 7): the guided detect → review → preflight →
   // trial → save flow for a service frame's `docker-compose` provisioning. `environmentWizardOpen`
   // is the modal flag; `environmentWizardFrameId` preselects the service frame the flow targets
@@ -761,8 +772,14 @@ function createInfraModals(resetHubReturn: ResetHubReturn) {
   }
   function closeProviderConnection() {
     infrastructureOpen.value = false
-    // Drop any consumed CLI prefill so re-opening the window normally doesn't re-seed the form.
+    // Drop any consumed CLI prefill so re-opening the window normally doesn't re-seed the form,
+    // and the anchor with it: an unconsumed target (the window was closed before the section
+    // rendered) would otherwise scroll the next, unrelated open.
     k3sSetupPrefill.value = null
+    infrastructureScrollTarget.value = null
+  }
+  function clearInfrastructureScrollTarget() {
+    infrastructureScrollTarget.value = null
   }
   // Capture a `cat-factory k3s` deep-link (`?infraSetup=local-k3s&…`) on app load: stash the
   // non-secret connection values, open the Infrastructure window on the Test-environments tab so
@@ -786,6 +803,10 @@ function createInfraModals(resetHubReturn: ResetHubReturn) {
     }
     resetHubReturn()
     infrastructureTab.value = 'environment'
+    // The hand-off is about ONE form, so land on it: the Kubernetes section sits below the
+    // default-provision picker, far enough down the tab that an operator arriving from the CLI
+    // would otherwise have to go looking for the fields it just told them about.
+    infrastructureScrollTarget.value = 'kubernetes'
     infrastructureOpen.value = true
     for (const key of [
       'infraSetup',
@@ -840,6 +861,8 @@ function createInfraModals(resetHubReturn: ResetHubReturn) {
     infrastructureTab,
     openInfrastructure,
     k3sSetupPrefill,
+    infrastructureScrollTarget,
+    clearInfrastructureScrollTarget,
     consumeK3sSetupDeepLink,
     environmentWizardOpen,
     environmentWizardFrameId,

package/app/types/providerConnections.ts

@@ -33,6 +33,15 @@ export type InfrastructureTab =
   | 'package-registries'
   | 'capability-credentials'
 
+/**
+ * A SECTION within an Infrastructure tab that a deep link can land the user on, rather than at
+ * the top of the tab with the section to hunt for. A closed union rather than a bare string, so
+ * the store's setter and the panel that honours it cannot drift apart silently: today's only
+ * member is the `kubernetes` provision-type section the `cat-factory k3s` hand-off targets, which
+ * sits below the default-provision picker in a tab long enough to need scrolling.
+ */
+export type InfrastructureScrollTarget = 'kubernetes'
+
 /** A workspace's provider binding, as exposed to clients (never secret values). */
 export interface ProviderConnection {
   /** The runner-backend kind for a runner-pool connection (`manifest` | `kubernetes`). */

package/app/utils/connectionFailures.ts

@@ -0,0 +1,32 @@
+import type { ConnectionFailureCause } from '@cat-factory/contracts'
+
+// A connection test that never got an ANSWER reports the transport failure CLASS as a
+// machine-readable `failureCause` (the backend does not localize prose), and the copy the operator
+// reads lives here. The backend's own English account of the failure, including the remedy it can
+// phrase with the concrete host in it, stays beside the headline as the technical detail.
+//
+// The exhaustive `Record<ConnectionFailureCause, …>` is the tier-2 drift guard, as in
+// `connectionWarnings.ts`: a backend that adds a cause fails this typecheck until the SPA has copy
+// for it, which the typed-key check cannot catch for a runtime-assembled key.
+
+/**
+ * Failure class → i18n key, or `null` where there is deliberately no headline to render.
+ *
+ * `unknown` is that case, and it is the reason the values are nullable: the chain was read and
+ * matched nothing, so the only honest statement about it is the backend's verbatim account, which
+ * is then rendered as the primary line instead of a headline that would have to invent a class.
+ */
+export const CONNECTION_FAILURE_CAUSE_KEYS: Record<ConnectionFailureCause, string | null> = {
+  refused: 'settings.providerConnection.test.causes.refused',
+  dns: 'settings.providerConnection.test.causes.dns',
+  timeout: 'settings.providerConnection.test.causes.timeout',
+  aborted: 'settings.providerConnection.test.causes.aborted',
+  unreachable: 'settings.providerConnection.test.causes.unreachable',
+  reset: 'settings.providerConnection.test.causes.reset',
+  'tls-untrusted': 'settings.providerConnection.test.causes.tlsUntrusted',
+  'tls-expired': 'settings.providerConnection.test.causes.tlsExpired',
+  'tls-hostname': 'settings.providerConnection.test.causes.tlsHostname',
+  'tls-protocol': 'settings.providerConnection.test.causes.tlsProtocol',
+  'invalid-header': 'settings.providerConnection.test.causes.invalidHeader',
+  unknown: null,
+}