fix(onboarding): only record the profile step once the API stored it

Addresses review feedback on the profile step:

- The server actions return an explicit {stored, error} outcome, so a
  transport failure or a rejection without an "errors" array is no longer
  read as success. The gate writes its marker and announces the submitted
  answers only when the row exists, and the skip path awaits the same
  outcome instead of assuming it.
- The local marker is keyed per tenant, so answering for one tenant no
  longer silences the step for another the same browser later opens.
- The profile step detail is a discriminated union: only a submitted step
  carries the answers.
- The detail route refuses with 405 instead of merely being hidden from
  the schema.
- The onboarding guide no longer claims zero backend coupling.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: alejandrobailo

api/src/backend/api/tests/test_onboarding_profile.py

@@ -141,3 +141,15 @@ def test_members_without_permissions_can_answer(
         response = _submit(authenticated_client_no_permissions_rbac, ANSWERS)
 
         assert response.status_code == status.HTTP_201_CREATED
+
+    def test_detail_route_is_refused(self, authenticated_client):
+        # One row per tenant, so the collection is the only meaningful read;
+        # the detail route must refuse rather than serve a second shape.
+        _submit(authenticated_client, ANSWERS)
+        profile = TenantOnboardingProfile.objects.get()
+
+        response = authenticated_client.get(
+            reverse("onboarding-profile-detail", kwargs={"pk": profile.id})
+        )
+
+        assert response.status_code == status.HTTP_405_METHOD_NOT_ALLOWED

api/src/backend/api/v1/views.py

@@ -9023,6 +9023,12 @@ def get_serializer_class(self):
             return TenantOnboardingProfileCreateSerializer
         return super().get_serializer_class()
 
+    def retrieve(self, request, *args, **kwargs):
+        # The resource is a single row per tenant, so the collection is the
+        # only meaningful read. `extend_schema(exclude=True)` hides the detail
+        # route from the docs; this is what actually closes it.
+        raise MethodNotAllowed(method="GET")
+
     def _stored_response(self, profile, http_status):
         return Response(
             TenantOnboardingProfileSerializer(

ui/actions/onboarding/profile.test.ts

@@ -0,0 +1,172 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const {
+  fetchMock,
+  getAuthHeadersMock,
+  handleApiErrorMock,
+  handleApiResponseMock,
+} = vi.hoisted(() => ({
+  fetchMock: vi.fn(),
+  getAuthHeadersMock: vi.fn(),
+  handleApiErrorMock: vi.fn(),
+  handleApiResponseMock: vi.fn(),
+}));
+
+vi.mock("next/cache", () => ({ revalidatePath: vi.fn() }));
+vi.mock("next/navigation", () => ({ redirect: vi.fn() }));
+
+vi.mock("@/lib", () => ({
+  apiBaseUrl: "https://api.example.com/api/v1",
+  getAuthHeaders: getAuthHeadersMock,
+}));
+
+vi.mock("@/lib/server-actions-helper", () => ({
+  handleApiError: handleApiErrorMock,
+  handleApiResponse: handleApiResponseMock,
+}));
+
+import {
+  isOnboardingProfileRecorded,
+  skipOnboardingProfile,
+  submitOnboardingProfile,
+} from "./profile";
+
+const ANSWERS = {
+  declared_cloud_accounts: "11-50",
+  declared_team_size: "2-5",
+  declared_role: "security",
+} as const;
+
+describe("onboarding profile actions", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", fetchMock);
+    fetchMock.mockReset();
+    getAuthHeadersMock.mockReset().mockResolvedValue({});
+    handleApiErrorMock.mockReset();
+    handleApiResponseMock.mockReset().mockResolvedValue({ data: { id: "p1" } });
+  });
+
+  it("reports a stored profile and sends the declared buckets", async () => {
+    // Given
+    fetchMock.mockResolvedValue(new Response("{}", { status: 201 }));
+
+    // When
+    const result = await submitOnboardingProfile(ANSWERS);
+
+    // Then
+    expect(result).toEqual({ stored: true });
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(url).toBe("https://api.example.com/api/v1/onboarding-profiles");
+    expect(JSON.parse(init.body).data).toEqual({
+      type: "onboarding-profiles",
+      attributes: ANSWERS,
+    });
+  });
+
+  it("records a skip as its own payload", async () => {
+    // Given
+    fetchMock.mockResolvedValue(new Response("{}", { status: 201 }));
+
+    // When
+    const result = await skipOnboardingProfile();
+
+    // Then
+    expect(result).toEqual({ stored: true });
+    expect(JSON.parse(fetchMock.mock.calls[0][1].body).data.attributes).toEqual(
+      {
+        skipped: true,
+      },
+    );
+  });
+
+  it("treats a transport failure as not stored", async () => {
+    // Given — the request never reaches the API.
+    fetchMock.mockRejectedValue(new Error("network down"));
+
+    // When
+    const result = await submitOnboardingProfile(ANSWERS);
+
+    // Then
+    expect(result.stored).toBe(false);
+    expect(result.error).toBeTruthy();
+    expect(handleApiErrorMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("treats a rejection without an errors array as not stored", async () => {
+    // Given — e.g. a 403, which `handleApiResponse` returns as a bare error.
+    fetchMock.mockResolvedValue(new Response("{}", { status: 403 }));
+    handleApiResponseMock.mockResolvedValue({
+      error: "Forbidden",
+      status: 403,
+    });
+
+    // When
+    const result = await submitOnboardingProfile(ANSWERS);
+
+    // Then
+    expect(result).toEqual({ stored: false, error: "Forbidden" });
+  });
+
+  it("surfaces the API's own message when the payload carries one", async () => {
+    // Given
+    fetchMock.mockResolvedValue(new Response("{}", { status: 400 }));
+    handleApiResponseMock.mockResolvedValue({
+      error: "Bad request",
+      errors: [{ detail: "This field is required." }],
+    });
+
+    // When
+    const result = await submitOnboardingProfile(ANSWERS);
+
+    // Then
+    expect(result).toEqual({
+      stored: false,
+      error: "This field is required.",
+    });
+  });
+
+  it("treats a thrown server error as not stored", async () => {
+    // Given — `handleApiResponse` throws on 5xx.
+    fetchMock.mockResolvedValue(new Response("{}", { status: 500 }));
+    handleApiResponseMock.mockRejectedValue(new Error("server error"));
+
+    // When
+    const result = await skipOnboardingProfile();
+
+    // Then
+    expect(result.stored).toBe(false);
+    expect(handleApiErrorMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("refuses answers outside the declared vocabulary", async () => {
+    // When / Then — validation happens before any request.
+    await expect(
+      submitOnboardingProfile({
+        ...ANSWERS,
+        declared_role: "ceo",
+      } as unknown as typeof ANSWERS),
+    ).rejects.toThrow();
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ["an empty list", { data: [] }, false],
+    ["a stored row", { data: [{ id: "p1" }] }, true],
+  ])("reads %s as recorded=%s", async (_, payload, expected) => {
+    // Given
+    fetchMock.mockResolvedValue(
+      new Response(JSON.stringify(payload), { status: 200 }),
+    );
+
+    // Then
+    expect(await isOnboardingProfileRecorded()).toBe(expected);
+  });
+
+  it("returns undefined when the read fails, so the gate fails open", async () => {
+    // Given
+    fetchMock.mockResolvedValue(new Response("{}", { status: 500 }));
+
+    // Then
+    expect(await isOnboardingProfileRecorded()).toBeUndefined();
+  });
+});

ui/actions/onboarding/profile.ts

@@ -14,6 +14,14 @@ import {
 const ONBOARDING_PROFILES_PATH = "/onboarding-profiles";
 const RESOURCE_TYPE = "onboarding-profiles";
 
+// Explicit outcome instead of the raw API payload: the caller records the
+// step as resolved only when the row was really written, and a transport
+// failure is as unsuccessful as a rejected payload.
+export interface OnboardingProfileResult {
+  stored: boolean;
+  error?: string;
+}
+
 const onboardingProfileAnswersSchema = z.object({
   declared_cloud_accounts: z.enum(
     Object.values(DECLARED_CLOUD_ACCOUNTS) as [string, ...string[]],
@@ -24,34 +32,68 @@ const onboardingProfileAnswersSchema = z.object({
   declared_role: z.enum(Object.values(DECLARED_ROLE) as [string, ...string[]]),
 });
 
-const postOnboardingProfile = async (attributes: Record<string, unknown>) => {
+const GENERIC_FAILURE = "The onboarding profile could not be saved.";
+
+const failureMessage = (payload: unknown): string | undefined => {
+  if (typeof payload !== "object" || payload === null) return undefined;
+  const result = payload as { error?: unknown; errors?: unknown };
+  if (Array.isArray(result.errors)) {
+    const detail = (result.errors[0] as { detail?: unknown })?.detail;
+    if (typeof detail === "string") return detail;
+  }
+  return typeof result.error === "string" ? result.error : undefined;
+};
+
+const postOnboardingProfile = async (
+  attributes: Record<string, unknown>,
+): Promise<OnboardingProfileResult> => {
   const headers = await getAuthHeaders({ contentType: true });
   const body = JSON.stringify({
     data: { type: RESOURCE_TYPE, attributes },
   });
 
+  let response: Response;
   try {
-    const response = await fetch(`${apiBaseUrl}${ONBOARDING_PROFILES_PATH}`, {
+    response = await fetch(`${apiBaseUrl}${ONBOARDING_PROFILES_PATH}`, {
       method: "POST",
       headers,
       body,
     });
-    return handleApiResponse(response);
   } catch (error) {
-    return handleApiError(error);
+    handleApiError(error);
+    return { stored: false, error: GENERIC_FAILURE };
+  }
+
+  // `handleApiResponse` reports to Sentry and throws on server errors; the
+  // status is what decides the outcome, since a rejection can come back
+  // without an `errors` array.
+  try {
+    const payload = await handleApiResponse(response);
+    if (!response.ok) {
+      return {
+        stored: false,
+        error: failureMessage(payload) ?? GENERIC_FAILURE,
+      };
+    }
+    return { stored: true };
+  } catch (error) {
+    handleApiError(error);
+    return { stored: false, error: GENERIC_FAILURE };
   }
 };
 
 // Records the three declared buckets. The API keeps the first answer per
 // tenant: a repeated submission answers 200 with the stored profile.
 export const submitOnboardingProfile = async (
   answers: OnboardingProfileAnswers,
-) => postOnboardingProfile(onboardingProfileAnswersSchema.parse(answers));
+): Promise<OnboardingProfileResult> =>
+  postOnboardingProfile(onboardingProfileAnswersSchema.parse(answers));
 
 // A skip is a fact worth storing: it separates "declined" from "never
 // shown" in the funnel.
-export const skipOnboardingProfile = async () =>
-  postOnboardingProfile({ skipped: true });
+export const skipOnboardingProfile =
+  async (): Promise<OnboardingProfileResult> =>
+    postOnboardingProfile({ skipped: true });
 
 // Whether the tenant already went through the step on any device. `undefined`
 // means the read failed; the gate fails open and does not force the modal.

ui/app/(prowler)/layout.tsx

@@ -7,6 +7,7 @@ import { ReactNode, Suspense } from "react";
 import { isOnboardingProfileRecorded } from "@/actions/onboarding/profile";
 import { getProviders } from "@/actions/providers";
 import { getScansByState } from "@/actions/scans/scans";
+import { auth } from "@/auth.config";
 import MainLayout from "@/components/layout/main-layout/main-layout";
 import {
   OnboardingCheckpointWatcher,
@@ -66,6 +67,9 @@ export default async function RootLayout({
   let hasProviders: boolean | undefined = false;
   // Same tri-state for the onboarding profile step; only new tenants pay the read.
   let profileRecorded: boolean | undefined = true;
+  // Scopes the step's local marker, so answering for one tenant does not
+  // silence it for another.
+  let tenantId: string | null = null;
 
   if (cloudEnabled) {
     const [providersData, scansByState] = await Promise.all([
@@ -82,7 +86,12 @@ export default async function RootLayout({
       ? providersData.data.length > 0
       : undefined;
     if (hasProviders === false) {
-      profileRecorded = await isOnboardingProfileRecorded();
+      const [recorded, session] = await Promise.all([
+        isOnboardingProfileRecorded(),
+        auth(),
+      ]);
+      profileRecorded = recorded;
+      tenantId = session?.tenantId ?? null;
     }
   }
 
@@ -113,6 +122,7 @@ export default async function RootLayout({
               <OnboardingProfileGate
                 hasProviders={hasProviders}
                 profileRecorded={profileRecorded}
+                tenantId={tenantId}
               />
               {/* Single mount point so the watcher survives post-connect navigation. */}
               <OnboardingCheckpointWatcher />