@cat-factory/app 0.228.1 → 0.230.0

package/app/components/auth/LoginScreen.vue

@@ -4,6 +4,7 @@ import { apiErrorEnvelope } from '~/composables/api/errors'
 import SecretInput from '~/components/common/SecretInput.vue'
 import type { VcsProvider } from '~/types/domain'
 import { VCS_PROVIDER_ICONS, VCS_PROVIDER_LABELS, VCS_PROVIDER_TOKEN_URLS } from '~/utils/vcs'
+import { SSO_ERROR_MESSAGE_KEYS } from '~/utils/sso'
 
 const auth = useAuthStore()
 const { t } = useI18n()
@@ -124,6 +125,18 @@ const showOAuthDivider = computed(
   () => auth.providers.password && (auth.providers.github || auth.providers.google),
 )
 
+// Enterprise SSO. Led with, above the consumer providers, because on a deployment that configures
+// it that is the intended way in — a person arriving at an org's board should not have to find
+// their company's button under two they must not use. The label is the operator's own wording
+// (it names their IdP), so it is rendered verbatim rather than through the catalog.
+const ssoLabel = computed(() => auth.sso?.label ?? '')
+// Translated copy for a refused round-trip, keyed off the machine-readable reason the backend
+// handed back. Each reason has its own wording because the remedies differ: a missing directory
+// group is something the user takes to IT, a failed code exchange is the operator's own config.
+const ssoErrorMessage = computed(() =>
+  auth.ssoError ? t(SSO_ERROR_MESSAGE_KEYS[auth.ssoError]) : null,
+)
+
 // Hosted (remote node) PAT login: the user pastes their OWN source-control PAT, which the
 // server resolves to an account and holds to its login/org/domain allowlist. The available
 // providers come from the server (`auth.patProviders`) — GitHub always, GitLab when configured,
@@ -157,6 +170,16 @@ async function submitRemotePat() {
   }
 }
 
+// Only divide SSO from what follows when something actually follows it.
+const showSsoDivider = computed(
+  () =>
+    auth.providers.sso &&
+    (auth.providers.github ||
+      auth.providers.google ||
+      auth.providers.password ||
+      remotePatProviders.value.length > 0),
+)
+
 // A remote deployment (node service / Worker) that advertises no sign-in method at all:
 // no OAuth, no password, no PAT, and not local mode. The auth gate still routes here (a
 // remote facade has no anonymous tier), so instead of a blank card we explain that
@@ -167,6 +190,7 @@ const noSignInMethod = computed(
     !auth.providers.github &&
     !auth.providers.google &&
     !auth.providers.password &&
+    !auth.providers.sso &&
     remotePatProviders.value.length === 0,
 )
 </script>
@@ -261,6 +285,41 @@ const noSignInMethod = computed(
         <span class="h-px flex-1 bg-slate-800" />
       </div>
 
+      <!-- A refused SSO round-trip: name the rule that refused, don't return the user to an
+           unchanged sign-in button. -->
+      <UAlert
+        v-if="ssoErrorMessage && mode !== 'forgot'"
+        class="mb-4"
+        color="error"
+        variant="subtle"
+        icon="i-lucide-shield-x"
+        :title="t('auth.sso.failedTitle')"
+        :description="ssoErrorMessage"
+        data-testid="sso-error"
+      />
+
+      <!-- Enterprise SSO: the deployment's OWN identity provider, led with where configured. -->
+      <div v-if="auth.providers.sso && mode !== 'forgot'" class="mb-2 space-y-2">
+        <UButton
+          block
+          size="lg"
+          color="primary"
+          icon="i-lucide-building-2"
+          data-testid="sso-signin"
+          @click="auth.loginWithSso(invite)"
+        >
+          {{ t('auth.sso.continueWith', { provider: ssoLabel }) }}
+        </UButton>
+      </div>
+
+      <div
+        v-if="showSsoDivider && mode !== 'forgot'"
+        class="my-4 flex items-center gap-3 text-xs text-slate-500"
+      >
+        <span class="h-px flex-1 bg-slate-800" /> {{ t('auth.login.or') }}
+        <span class="h-px flex-1 bg-slate-800" />
+      </div>
+
       <!-- OAuth providers -->
       <div v-if="mode !== 'forgot'" class="space-y-2">
         <UButton

package/app/components/board/AddTaskModal.vue

@@ -895,6 +895,7 @@ function openReviewFrictionDialog(conflict: NonNullable<ReturnType<typeof parseC
                     : t('board.addTask.descriptionPlaceholder')
                 "
                 class="w-full"
+                data-testid="add-task-description"
               />
             </UFormField>
           </template>

package/app/components/board/nodes/TaskCard.vue

@@ -406,6 +406,7 @@ function selectTask() {
           :icon="!runnable ? 'i-lucide-lock' : sandboxed ? 'i-lucide-shield' : 'i-lucide-play'"
           :loading="starting"
           :disabled="!runnable || starting"
+          data-testid="task-start"
           :title="
             !runnable
               ? t('board.task.waitingOn', { deps: unmet.map((d) => d.title).join(', ') })

package/app/components/inputGate/InputGateNotice.vue

@@ -148,6 +148,9 @@ async function resolve(choice: 'recheck' | 'proceed') {
             v-for="issue in issues"
             :key="`${issue.code}:${issue.field?.key ?? ''}`"
             class="flex items-start gap-2 text-xs"
+            data-testid="input-gate-issue"
+            :data-issue-code="issue.code"
+            :data-issue-severity="issue.severity"
           >
             <UBadge
               :color="issue.severity === 'blocking' ? 'warning' : 'neutral'"

package/app/components/judge/JudgeResultView.vue

@@ -170,6 +170,17 @@ async function act(choice: 'proceed' | 'bounce' | 'stop') {
           </span>
         </div>
 
+        <!-- The rubric asked for a model this deployment cannot serve, so something else scored
+             the work. Only this case is shown: a pin that was honoured says nothing the model
+             name doesn't, and being overridden by the task's own choice is the normal outcome. -->
+        <p
+          v-if="judge.modelPin?.status === 'unavailable'"
+          class="mt-2 rounded-md border border-amber-500/30 bg-amber-500/5 px-3 py-2 text-[12px] leading-relaxed text-amber-200"
+          data-testid="judge-model-pin"
+        >
+          {{ t('judge.modelPinUnavailable', { model: judge.modelPin.requested }) }}
+        </p>
+
         <!-- Why the judge did nothing, when it did nothing. A skipped judge must never read
              like a clean pass. -->
         <p
@@ -288,6 +299,8 @@ async function act(choice: 'proceed' | 'bounce' | 'stop') {
               v-for="round in rounds"
               :key="round.round"
               class="flex flex-wrap items-center gap-2 rounded-md border border-slate-800 bg-slate-950/40 px-3 py-1.5 text-[12px] text-slate-300"
+              data-testid="judge-round"
+              :data-round-disposition="round.disposition"
             >
               <span class="text-slate-500">{{ t('judge.round', { round: round.round }) }}</span>
               <span class="font-medium text-slate-100">{{

package/app/components/panels/inspector/TaskExecution.vue

@@ -373,6 +373,7 @@ async function mergePr() {
             <button
               type="button"
               class="flex min-w-0 cursor-pointer items-center gap-2 text-start transition hover:text-white"
+              data-testid="run-step-open"
               :title="
                 s.output
                   ? t('inspector.execution.viewDetailsOutput')

package/app/components/requirements/RequirementsReviewWindow.vue

@@ -708,6 +708,7 @@ async function resolveExceeded(choice: 'extra-round' | 'proceed' | 'stop-reset')
           <div
             v-if="incorporated"
             class="mb-4 flex items-center gap-2 rounded-lg border border-emerald-900/60 bg-emerald-950/30 p-4 text-sm text-emerald-300"
+            data-testid="requirements-settled"
           >
             <UIcon name="i-lucide-circle-check" class="h-5 w-5 shrink-0" />
             {{ t('requirements.settled') }}
@@ -760,6 +761,9 @@ async function resolveExceeded(choice: 'extra-round' | 'proceed' | 'stop-reset')
               <div
                 class="rounded-lg border border-slate-800 bg-slate-900/60 p-3"
                 :class="{ 'opacity-60': item.status === 'dismissed' }"
+                data-testid="requirements-finding"
+                :data-finding-status="item.status"
+                :data-finding-severity="item.severity"
               >
                 <div class="flex items-start gap-2">
                   <UIcon
@@ -831,6 +835,7 @@ async function resolveExceeded(choice: 'extra-round' | 'proceed' | 'stop-reset')
                           size="xs"
                           :icon="opt.icon"
                           :disabled="frozen"
+                          :data-testid="`requirements-mode-${opt.mode}`"
                           @click="setMode(item, opt.mode)"
                         >
                           {{ t(opt.labelKey) }}
@@ -881,6 +886,7 @@ async function resolveExceeded(choice: 'extra-round' | 'proceed' | 'stop-reset')
                           class="mt-2 w-full"
                           :placeholder="t('requirements.answerPlaceholder')"
                           :disabled="frozen"
+                          data-testid="requirements-answer"
                           @blur="persistDraft(item)"
                         />
                         <p
@@ -1170,6 +1176,7 @@ async function resolveExceeded(choice: 'extra-round' | 'proceed' | 'stop-reset')
               :loading="acting"
               :disabled="!access.canExecuteRuns.value"
               :title="access.canExecuteRuns.value ? undefined : t('access.noRunExecute')"
+              data-testid="requirements-proceed"
               @click="proceed"
             >
               {{ t('requirements.actions.proceedNothing') }}
@@ -1183,6 +1190,7 @@ async function resolveExceeded(choice: 'extra-round' | 'proceed' | 'stop-reset')
               :loading="reworking"
               :disabled="!canIncorporate || !access.canExecuteRuns.value"
               :title="access.canExecuteRuns.value ? undefined : t('access.noRunExecute')"
+              data-testid="requirements-incorporate"
               @click="incorporate()"
             >
               {{ t('requirements.actions.incorporateAnswers') }}

package/app/components/settings/McpOAuthCallbackScreen.vue

@@ -0,0 +1,103 @@
+<script setup lang="ts">
+import { onMounted, ref } from 'vue'
+
+// Where a vendor's authorization server sends the operator's browser back to after they approve a
+// remote MCP tool server (`/mcp-oauth-callback?code=…&state=…`).
+//
+// A page in the APP rather than a route on the backend, which is the security shape of this flow
+// rather than a routing preference: a redirect is a third-party navigation carrying no bearer
+// token, so a backend receiver could never tell WHO was completing the grant. This page re-presents
+// the two values over the authenticated API, where the session, the "same user who started it"
+// binding and the `secrets.manage` re-check all actually run.
+//
+// It is NOT a public route (unlike the password reset beside it): an expired session renders the
+// login screen on this same URL, and once the operator signs in the query string is still here and
+// the grant completes. That is the correct behaviour, not a gap.
+
+const api = useApi()
+const { t } = useI18n()
+
+const state = ref<'working' | 'done' | 'failed'>('working')
+const detail = ref<string | null>(null)
+const serverId = ref<string | null>(null)
+
+function query(name: string): string {
+  if (typeof window === 'undefined') return ''
+  return new URLSearchParams(window.location.search).get(name) ?? ''
+}
+
+onMounted(async () => {
+  // An authorization server that REFUSED reports it here rather than on the token endpoint, so the
+  // operator's own "Deny" and a misconfigured client both arrive as this. Named rather than folded
+  // into "no code": one is nothing to fix and the other is the client registration.
+  const denied = query('error')
+  if (denied) {
+    state.value = 'failed'
+    detail.value = query('error_description') || denied
+    return
+  }
+  const code = query('code')
+  const sealed = query('state')
+  if (!code || !sealed) {
+    state.value = 'failed'
+    detail.value = t('settings.toolServers.oauth.callback.missingParams')
+    return
+  }
+  try {
+    const result = await api.completeToolServerOAuth({ code, state: sealed })
+    serverId.value = result.serverId
+    state.value = 'done'
+  } catch (e) {
+    state.value = 'failed'
+    detail.value =
+      (e as { data?: { error?: { message?: string } } })?.data?.error?.message ??
+      t('settings.toolServers.oauth.callback.failed')
+  }
+})
+
+function backToApp() {
+  if (typeof window !== 'undefined') window.location.assign('/')
+}
+</script>
+
+<template>
+  <div
+    class="flex h-screen w-screen items-center justify-center bg-slate-950 text-slate-100"
+    data-testid="mcp-oauth-callback"
+  >
+    <div
+      class="w-full max-w-sm rounded-xl border border-slate-800 bg-slate-900/80 p-8 text-center backdrop-blur"
+    >
+      <template v-if="state === 'working'">
+        <UIcon name="i-lucide-loader" class="mx-auto mb-3 h-10 w-10 animate-spin text-indigo-400" />
+        <h1 class="mb-1 text-lg font-semibold text-white">
+          {{ t('settings.toolServers.oauth.callback.working') }}
+        </h1>
+      </template>
+
+      <template v-else-if="state === 'done'">
+        <UIcon name="i-lucide-check-circle" class="mx-auto mb-3 h-10 w-10 text-emerald-400" />
+        <h1 class="mb-1 text-lg font-semibold text-white" data-testid="mcp-oauth-callback-done">
+          {{ t('settings.toolServers.oauth.callback.done', { server: serverId }) }}
+        </h1>
+        <p class="mb-6 text-sm text-slate-400">
+          {{ t('settings.toolServers.oauth.callback.doneHint') }}
+        </p>
+        <UButton block color="primary" @click="backToApp">
+          {{ t('settings.toolServers.oauth.callback.back') }}
+        </UButton>
+      </template>
+
+      <template v-else>
+        <UIcon name="i-lucide-alert-triangle" class="mx-auto mb-3 h-10 w-10 text-red-400" />
+        <h1 class="mb-1 text-lg font-semibold text-white" data-testid="mcp-oauth-callback-failed">
+          {{ t('settings.toolServers.oauth.callback.failedTitle') }}
+        </h1>
+        <p class="mb-6 text-sm break-words text-slate-400">{{ detail }}</p>
+        <UButton block color="neutral" variant="subtle" @click="backToApp">
+          {{ t('settings.toolServers.oauth.callback.back') }}
+        </UButton>
+      </template>
+    </div>
+  </div>
+</template>

package/app/components/settings/ToolServerChecklist.vue

@@ -40,6 +40,8 @@ const STATUS_LABELS = computed<Record<ToolServerProbeStatus, string>>(() => ({
   ok: t('settings.toolServers.status.ok'),
   credentials_missing: t('settings.toolServers.status.credentialsMissing'),
   credential_refused: t('settings.toolServers.status.credentialRefused'),
+  oauth_not_connected: t('settings.toolServers.status.oauthNotConnected'),
+  oauth_token_failed: t('settings.toolServers.status.oauthTokenFailed'),
   unreachable: t('settings.toolServers.status.unreachable'),
   http_error: t('settings.toolServers.status.httpError'),
   protocol_error: t('settings.toolServers.status.protocolError'),
@@ -53,6 +55,36 @@ const NOT_PROBEABLE_LABELS = computed<Record<ToolServerNotProbeableReason, strin
 
 const servers = computed<ToolServerView[]>(() => store.view?.servers ?? [])
 
+/**
+ * Whether a row offers the Connect / Disconnect pair.
+ *
+ * Only the INTERACTIVE grant does. A `client_credentials` declaration authenticates as the
+ * deployment's own client and mints its token on the first dispatch that needs one, so there is
+ * nothing for a person to authorise and a button would promise an action that does not exist.
+ */
+function isInteractive(server: ToolServerView): boolean {
+  return server.oauth?.grant === 'authorization_code'
+}
+
+async function connect(id: string) {
+  try {
+    await store.connectOAuth(id)
+  } catch (e) {
+    // Everything that can refuse does so BEFORE the browser leaves the app: an unconfigured
+    // redirect URL, a deployment with no grant store, an authorization server that publishes no
+    // metadata. Each carries a `details.reason` the shared funnel maps to translated copy.
+    present(e, 'settings.toolServers.toast.connectFailed')
+  }
+}
+
+async function disconnect(id: string) {
+  try {
+    await store.disconnectOAuth(id)
+  } catch (e) {
+    present(e, 'settings.toolServers.toast.disconnectFailed')
+  }
+}
+
 function resultFor(id: string) {
   return store.results[id]
 }
@@ -138,6 +170,85 @@ async function runProbe(id: string) {
         }}
       </p>
 
+      <!-- OAuth. Absent for a server that authenticates with a static credential, so the Connect
+           affordance never appears on a row it does not apply to. `connected` and `lastError` are
+           rendered TOGETHER rather than as alternatives: a grant that is on file and no longer
+           producing tokens is exactly the state that reads as working and is not. -->
+      <div
+        v-if="server.oauth"
+        class="space-y-1 rounded-md border border-slate-800 bg-slate-900/40 p-2"
+        :data-testid="`tool-server-oauth-${server.id}`"
+      >
+        <div class="flex flex-wrap items-center gap-2">
+          <UBadge
+            :color="server.oauth.connected ? 'success' : 'neutral'"
+            variant="soft"
+            size="sm"
+            :data-testid="`tool-server-oauth-state-${server.id}`"
+          >
+            {{
+              server.oauth.connected
+                ? t('settings.toolServers.oauth.connected')
+                : isInteractive(server)
+                  ? t('settings.toolServers.oauth.notConnected')
+                  : t('settings.toolServers.oauth.machineGrant')
+            }}
+          </UBadge>
+          <span v-if="server.oauth.connectedBy" class="text-[11px] text-slate-400">
+            {{ t('settings.toolServers.oauth.connectedBy', { user: server.oauth.connectedBy }) }}
+          </span>
+        </div>
+
+        <p v-if="server.oauth.scopes?.length" class="text-[11px] text-slate-400">
+          {{ t('settings.toolServers.oauth.scopes', { scopes: server.oauth.scopes.join(', ') }) }}
+        </p>
+        <!-- A grant with no refresh token works until its access token expires and then needs
+             granting again by hand. Said BEFORE it happens, which is the only time it is useful. -->
+        <p
+          v-if="server.oauth.connected && server.oauth.refreshable === false"
+          class="text-[11px] text-amber-400"
+        >
+          {{ t('settings.toolServers.oauth.notRefreshable') }}
+        </p>
+        <p
+          v-if="server.oauth.lastError"
+          class="text-[11px] text-red-400"
+          :data-testid="`tool-server-oauth-error-${server.id}`"
+        >
+          {{ t('settings.toolServers.oauth.lastError', { detail: server.oauth.lastError }) }}
+        </p>
+
+        <div v-if="isInteractive(server)" class="flex flex-wrap items-center gap-2 pt-1">
+          <UButton
+            size="xs"
+            variant="subtle"
+            icon="i-lucide-link"
+            :loading="store.connecting === server.id"
+            :disabled="store.connecting !== null"
+            :data-testid="`tool-server-connect-${server.id}`"
+            @click="connect(server.id)"
+          >
+            {{
+              server.oauth.connected
+                ? t('settings.toolServers.oauth.reconnect')
+                : t('settings.toolServers.oauth.connect')
+            }}
+          </UButton>
+          <UButton
+            v-if="server.oauth.connected"
+            size="xs"
+            variant="ghost"
+            color="error"
+            :loading="store.connecting === server.id"
+            :disabled="store.connecting !== null"
+            :data-testid="`tool-server-disconnect-${server.id}`"
+            @click="disconnect(server.id)"
+          >
+            {{ t('settings.toolServers.oauth.disconnect') }}
+          </UButton>
+        </div>
+      </div>
+
       <div class="flex flex-wrap items-center gap-2 pt-1">
         <UButton
           v-if="server.probeable"

package/app/composables/api/toolServers.ts

@@ -1,4 +1,10 @@
-import { listToolServersContract, probeToolServerContract } from '@cat-factory/contracts'
+import {
+  completeToolServerOAuthContract,
+  disconnectToolServerOAuthContract,
+  listToolServersContract,
+  probeToolServerContract,
+  startToolServerOAuthContract,
+} from '@cat-factory/contracts'
 import type { ApiContext } from './context'
 
 /**
@@ -17,5 +23,21 @@ export function toolServersApi({ send, ws }: ApiContext) {
 
     probeToolServer: (workspaceId: string, id: string) =>
       send(probeToolServerContract, { pathPrefix: ws(workspaceId), pathParams: { id } }),
+
+    // Begin an interactive OAuth grant: answers with the VENDOR's authorization URL for the
+    // operator's browser to follow, rather than redirecting, since a redirect from a `fetch` lands
+    // in a cross-origin document this app cannot observe.
+    startToolServerOAuth: (workspaceId: string, id: string) =>
+      send(startToolServerOAuthContract, { pathPrefix: ws(workspaceId), pathParams: { id } }),
+
+    disconnectToolServerOAuth: (workspaceId: string, id: string) =>
+      send(disconnectToolServerOAuthContract, { pathPrefix: ws(workspaceId), pathParams: { id } }),
+
+    // Finish a grant with what the vendor's redirect carried. NOT workspace-prefixed: the board is
+    // sealed into the `state`, so the caller does not know it and could not be trusted with it
+    // anyway. This is the request that makes the flow's session, user binding and permission
+    // re-check enforceable, which a vendor's redirect landing on the backend never could.
+    completeToolServerOAuth: (body: { code: string; state: string }) =>
+      send(completeToolServerOAuthContract, { body }),
   }
 }

package/app/pages/mcp-oauth-callback.vue

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

package/app/stores/auth/mothership.ts

@@ -1,6 +1,8 @@
 import type { Ref } from 'vue'
+import { SSO_ERROR_FRAGMENT_KEY, parseSsoErrorReason } from '@cat-factory/contracts'
 import type { LocalModeConfig } from '@cat-factory/contracts'
 import type { AuthUser } from '~/types/domain'
+import type { SsoLoginFailure } from '~/utils/sso'
 
 /**
  * Shared reactive state + injected dependencies the auth-store redirect factory closes over.
@@ -13,6 +15,8 @@ export interface AuthRedirectContext {
   token: Ref<string | null>
   localMode: Ref<LocalModeConfig | null>
   mothershipError: Ref<string | null>
+  /** Why the last enterprise-SSO round-trip produced no session, when one was refused. */
+  ssoError: Ref<SsoLoginFailure | null>
   /** Apply a freshly-minted token + user (the session factory's setter). */
   applySession: (result: { token: string; user: AuthUser }) => void
 }
@@ -23,7 +27,7 @@ export interface AuthRedirectContext {
  * mode — exchanging a returning MOTHERSHIP session for a local one.
  */
 export function createAuthRedirectActions(ctx: AuthRedirectContext) {
-  const { api, token, localMode, mothershipError, applySession } = ctx
+  const { api, token, localMode, mothershipError, ssoError, applySession } = ctx
 
   /** Pull a token handed back in the post-login URL fragment (#token=…). */
   function consumeRedirectToken() {
@@ -35,6 +39,27 @@ export function createAuthRedirectActions(ctx: AuthRedirectContext) {
     history.replaceState(null, '', window.location.pathname + window.location.search)
   }
 
+  /**
+   * Pull the reason a REFUSED enterprise-SSO round-trip handed back (`#sso_error=<reason>`), the
+   * sibling of the `#token=` a successful one sets.
+   *
+   * A fragment rather than a query for the same reason the token is: it never reaches a server log
+   * or a `Referer`, and the reason names the deployment's own admission rules. Stripped from the
+   * URL afterwards so a reload doesn't resurrect a stale failure.
+   */
+  function consumeSsoError() {
+    if (typeof window === 'undefined') return
+    const match = new RegExp(`(?:^#|[#&])${SSO_ERROR_FRAGMENT_KEY}=([^&]+)`).exec(
+      window.location.hash,
+    )
+    if (!match) return
+    // An unrecognised value came from a newer backend than this build: reported as `unknown`
+    // rather than rendered raw, and never dropped — the user clicked a button and is owed an
+    // answer about why they are back here.
+    ssoError.value = parseSsoErrorReason(decodeURIComponent(match[1]!)) ?? 'unknown'
+    history.replaceState(null, '', window.location.pathname + window.location.search)
+  }
+
   /**
    * Mothership mode: when the mothership OAuth redirect returns here (flagged
    * `?mothership_connect=1`), the URL fragment carries a MOTHERSHIP session — not a local one.
@@ -101,6 +126,7 @@ export function createAuthRedirectActions(ctx: AuthRedirectContext) {
 
   return {
     consumeRedirectToken,
+    consumeSsoError,
     maybeConnectMothership,
     signInViaMothership,
     maybeAcceptInvite,

package/app/stores/auth/session.ts

@@ -44,6 +44,16 @@ export function createAuthSessionActions(ctx: AuthSessionContext) {
     window.location.href = `${apiBase}/auth/google/login?${redirectTarget(invite)}`
   }
 
+  /**
+   * Send the browser to the deployment's OWN identity provider (enterprise SSO), returning here
+   * after. One entry point whichever IdP is configured: the backend resolves the provider from its
+   * discovery document, so there is nothing per-vendor for the SPA to know.
+   */
+  function loginWithSso(invite?: string) {
+    if (typeof window === 'undefined') return
+    window.location.href = `${apiBase}/auth/sso/login?${redirectTarget(invite)}`
+  }
+
   /** Apply a freshly-minted token + user (from password signup/login). */
   function applySession(result: { token: string; user: AuthUser }) {
     token.value = result.token
@@ -107,6 +117,7 @@ export function createAuthSessionActions(ctx: AuthSessionContext) {
     applySession,
     login,
     loginWithGoogle,
+    loginWithSso,
     signup,
     passwordLogin,
     patLogin,

package/app/stores/auth/ssoError.spec.ts

@@ -0,0 +1,64 @@
+import { ref } from 'vue'
+import { beforeEach, describe, expect, it } from 'vitest'
+import { createAuthRedirectActions } from './mothership'
+import type { SsoLoginFailure } from '~/utils/sso'
+
+// The other half of the SSO refusal contract: the backend lands the browser here with a
+// machine-readable reason in the fragment, and this is what turns it into state the login screen
+// renders. Worth pinning because the failure mode is silent — a reason the SPA drops leaves the
+// user back on the same sign-in button with no explanation for the click that just failed.
+
+/** Point `window.location` + `history` at a URL the consumer can read and rewrite. */
+function setUrl(path: string): void {
+  history.replaceState(null, '', path)
+}
+
+function actions() {
+  const ssoError = ref<SsoLoginFailure | null>(null)
+  const factory = createAuthRedirectActions({
+    api: {} as never,
+    token: ref<string | null>(null),
+    localMode: ref(null),
+    mothershipError: ref<string | null>(null),
+    ssoError,
+    applySession: () => {},
+  })
+  return { ...factory, ssoError }
+}
+
+describe('consumeSsoError', () => {
+  beforeEach(() => setUrl('/'))
+
+  it('reads a known reason off the fragment', () => {
+    setUrl('/#sso_error=group_required')
+    const a = actions()
+    a.consumeSsoError()
+    expect(a.ssoError.value).toBe('group_required')
+  })
+
+  it('strips the fragment so a reload does not resurrect a stale failure', () => {
+    setUrl('/board?ws=ws_1#sso_error=state_invalid')
+    actions().consumeSsoError()
+    expect(window.location.hash).toBe('')
+    // The rest of the URL is left alone.
+    expect(window.location.pathname + window.location.search).toBe('/board?ws=ws_1')
+  })
+
+  it('reports an unrecognised reason as `unknown` rather than dropping it', () => {
+    // A reason from a NEWER backend than this build. Rendering the raw wire token to a user is
+    // wrong; showing nothing after a failed sign-in is worse.
+    setUrl('/#sso_error=reason_from_the_future')
+    const a = actions()
+    a.consumeSsoError()
+    expect(a.ssoError.value).toBe('unknown')
+  })
+
+  it('leaves the state untouched when the fragment carries no SSO error', () => {
+    setUrl('/#token=abc')
+    const a = actions()
+    a.consumeSsoError()
+    expect(a.ssoError.value).toBeNull()
+    // The session token is another consumer's to read, so the fragment must survive.
+    expect(window.location.hash).toBe('#token=abc')
+  })
+})