fix(keychain): handle structured Prove verification results

packages/keychain/src/components/identity/VerifyIdentityDrawer.test.tsx

@@ -7,6 +7,11 @@ const mocks = vi.hoisted(() => ({
 }));
 
 vi.mock("@/utils/api", () => ({
+  AccountVerifyReasonCode: {
+    NotVerified: "NOT_VERIFIED",
+    ProviderUnavailable: "PROVIDER_UNAVAILABLE",
+    Verified: "VERIFIED",
+  },
   useAccountVerifyMutation: () => ({
     mutateAsync: mocks.verifyAsync,
     isLoading: false,
@@ -48,7 +53,14 @@ vi.mock("./error", () => ({
 describe("VerifyIdentityDrawer", () => {
   beforeEach(() => {
     vi.clearAllMocks();
-    mocks.verifyAsync.mockResolvedValue({ accountVerify: true });
+    mocks.verifyAsync.mockResolvedValue({
+      accountVerify: {
+        verified: true,
+        reasonCode: "VERIFIED",
+        retryable: false,
+        correlationId: "verify-success",
+      },
+    });
   });
 
   it("does not report cancellation after successful Prove verification", async () => {
@@ -78,4 +90,55 @@ describe("VerifyIdentityDrawer", () => {
     await refresh;
     expect(onClose).not.toHaveBeenCalled();
   });
+
+  it("keeps entered details and shows an actionable mismatch message", async () => {
+    mocks.verifyAsync.mockResolvedValue({
+      accountVerify: {
+        verified: false,
+        reasonCode: "NOT_VERIFIED",
+        retryable: false,
+        correlationId: "verify-mismatch",
+      },
+    });
+
+    render(
+      <VerifyIdentityDrawer isOpen onClose={vi.fn()} onVerified={vi.fn()} />,
+    );
+
+    const firstName = screen.getByLabelText("First Name");
+    const lastName = screen.getByLabelText("Last Name");
+    fireEvent.change(firstName, { target: { value: "Ada" } });
+    fireEvent.change(lastName, { target: { value: "Lovelace" } });
+    fireEvent.click(screen.getByRole("button", { name: "Continue" }));
+
+    await screen.findByText(/couldn't verify these details/i);
+    expect(firstName).toHaveValue("Ada");
+    expect(lastName).toHaveValue("Lovelace");
+    expect(screen.getByText(/verify-mismatch/)).toBeInTheDocument();
+  });
+
+  it("shows provider outages as retryable with a support reference", async () => {
+    mocks.verifyAsync.mockResolvedValue({
+      accountVerify: {
+        verified: false,
+        reasonCode: "PROVIDER_UNAVAILABLE",
+        retryable: true,
+        correlationId: "verify-provider",
+      },
+    });
+
+    render(
+      <VerifyIdentityDrawer isOpen onClose={vi.fn()} onVerified={vi.fn()} />,
+    );
+    fireEvent.change(screen.getByLabelText("First Name"), {
+      target: { value: "Ada" },
+    });
+    fireEvent.change(screen.getByLabelText("Last Name"), {
+      target: { value: "Lovelace" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: "Continue" }));
+
+    await screen.findByText(/temporarily unavailable/i);
+    expect(screen.getByText(/verify-provider/)).toBeInTheDocument();
+  });
 });

packages/keychain/src/components/identity/VerifyIdentityDrawer.tsx

@@ -9,7 +9,7 @@ import {
   isValidCalendarDate,
   type DateValue,
 } from "@cartridge/controller-ui";
-import { useAccountVerifyMutation } from "@/utils/api";
+import { AccountVerifyReasonCode, useAccountVerifyMutation } from "@/utils/api";
 import { VerifyErrorAlert } from "./error";
 
 interface VerifyIdentityDrawerProps {
@@ -65,8 +65,23 @@ export function VerifyIdentityDrawer({
           // sandbox: true, //returns true, but do not store
         },
       });
-      if (!result.accountVerify) {
-        setError("Account verification failed");
+      if (!result.accountVerify.verified) {
+        const reference = result.accountVerify.correlationId
+          ? ` Reference: ${result.accountVerify.correlationId}`
+          : "";
+        if (
+          result.accountVerify.reasonCode ===
+            AccountVerifyReasonCode.ProviderUnavailable ||
+          result.accountVerify.retryable
+        ) {
+          setError(
+            `Identity verification service is temporarily unavailable. Please try again.${reference}`,
+          );
+        } else {
+          setError(
+            `We couldn't verify these details. Check that your legal name and date of birth match the identity associated with your verified phone number.${reference}`,
+          );
+        }
         return;
       }
       // The owner closes the drawer after it refreshes verified user data.

packages/keychain/src/components/identity/error.tsx

@@ -22,12 +22,25 @@ export const VerifyErrorAlert = ({ error }: { error: string }) => {
       };
     }
 
-    return error.toLowerCase().includes("invalid or expired verification")
-      ? { title: "Invalid or expired verification code" }
-      : {
-          title: "Verification failed",
-          description: "Please try again.",
-        };
+    if (error.toLowerCase().includes("invalid or expired verification")) {
+      return { title: "Invalid or expired verification code" };
+    }
+    if (error.startsWith("Identity verification service")) {
+      return {
+        title: "Verification service unavailable",
+        description: error,
+      };
+    }
+    if (error.startsWith("We couldn't verify these details")) {
+      return {
+        title: "Details could not be verified",
+        description: error,
+      };
+    }
+    return {
+      title: "Verification failed",
+      description: "Please try again.",
+    };
   }, [advancedView, error]);
   return <ErrorAlert title={title} description={description} />;
 };

packages/keychain/src/utils/api/account.graphql

@@ -120,7 +120,12 @@ query AccountSearch($query: String!, $limit: Int = 5) {
 }
 
 mutation AccountVerify($input: AccountVerifyInput!) {
-  accountVerify(input: $input)
+  accountVerify(input: $input) {
+    verified
+    reasonCode
+    retryable
+    correlationId
+  }
 }
 
 mutation DeleteMe {

packages/keychain/src/utils/api/generated.ts

@@ -256,6 +256,20 @@ export type AccountVerifyInput = {
   sandbox?: InputMaybe<Scalars["Boolean"]>;
 };
 
+export enum AccountVerifyReasonCode {
+  NotVerified = "NOT_VERIFIED",
+  ProviderUnavailable = "PROVIDER_UNAVAILABLE",
+  Verified = "VERIFIED",
+}
+
+export type AccountVerifyResult = {
+  __typename?: "AccountVerifyResult";
+  correlationId: Scalars["String"];
+  reasonCode: AccountVerifyReasonCode;
+  retryable: Scalars["Boolean"];
+  verified: Scalars["Boolean"];
+};
+
 /**
  * AccountWhereInput is used for filtering Account objects.
  * Input was generated by ent.
@@ -3245,7 +3259,7 @@ export type MetricsResult = {
 
 export type Mutation = {
   __typename?: "Mutation";
-  accountVerify: Scalars["Boolean"];
+  accountVerify: AccountVerifyResult;
   addOwner: Scalars["Boolean"];
   addPolicies?: Maybe<Array<PaymasterPolicy>>;
   addToTeam: Scalars["Boolean"];
@@ -7402,7 +7416,13 @@ export type AccountVerifyMutationVariables = Exact<{
 
 export type AccountVerifyMutation = {
   __typename?: "Mutation";
-  accountVerify: boolean;
+  accountVerify: {
+    __typename?: "AccountVerifyResult";
+    verified: boolean;
+    reasonCode: AccountVerifyReasonCode;
+    retryable: boolean;
+    correlationId: string;
+  };
 };
 
 export type DeleteMeMutationVariables = Exact<{ [key: string]: never }>;
@@ -8329,7 +8349,12 @@ export const useAccountSearchQuery = <
   );
 export const AccountVerifyDocument = `
     mutation AccountVerify($input: AccountVerifyInput!) {
-  accountVerify(input: $input)
+  accountVerify(input: $input) {
+    verified
+    reasonCode
+    retryable
+    correlationId
+  }
 }
     `;
 export const useAccountVerifyMutation = <TError = unknown, TContext = unknown>(

packages/ui/src/utils/api/cartridge/generated.ts

@@ -252,6 +252,20 @@ export type AccountVerifyInput = {
   sandbox?: InputMaybe<Scalars['Boolean']>;
 };
 
+export enum AccountVerifyReasonCode {
+  NotVerified = 'NOT_VERIFIED',
+  ProviderUnavailable = 'PROVIDER_UNAVAILABLE',
+  Verified = 'VERIFIED'
+}
+
+export type AccountVerifyResult = {
+  __typename?: 'AccountVerifyResult';
+  correlationId: Scalars['String'];
+  reasonCode: AccountVerifyReasonCode;
+  retryable: Scalars['Boolean'];
+  verified: Scalars['Boolean'];
+};
+
 /**
  * AccountWhereInput is used for filtering Account objects.
  * Input was generated by ent.
@@ -3240,7 +3254,7 @@ export type MetricsResult = {
 
 export type Mutation = {
   __typename?: 'Mutation';
-  accountVerify: Scalars['Boolean'];
+  accountVerify: AccountVerifyResult;
   addOwner: Scalars['Boolean'];
   addPolicies?: Maybe<Array<PaymasterPolicy>>;
   addToTeam: Scalars['Boolean'];