feat: hand off popup auth for restrictive iframe environments (#2462)

## Summary

This PR adds a WebAuthn popup fallback for restrictive iframe
environments and switches the popup completion path to an explicit state
handoff back into the iframe.

The original approach assumed the popup could persist controller/session
state to first-party storage and the embedded keychain iframe could then
reload it with `fromStore()`. That is not reliable across browsers
because popup storage and iframe storage can be partitioned differently,
especially in Safari and other restrictive iframe contexts.

The fix is to let the popup complete the WebAuthn and session flow,
export the resulting controller/session state, return it to the opener
via `postMessage`, and import/persist it inside the iframe.

## Dependency

Depends on `cartridge-gg/controller-rs#98`, which adds the import/export
APIs used by this PR:
- `ControllerFactory.fromMetadata(...)`
- `CartridgeAccount.exportMetadata()`
- `CartridgeAccount.exportAuthorizedSession(...)`
- `CartridgeAccount.importSession(...)`

## Why

Some iframe environments do not allow:

- `publickey-credentials-create`
- `publickey-credentials-get`

That breaks passkey auth inside the embedded keychain iframe.

Even when a popup can perform WebAuthn successfully, relying on
popup-written local storage is not a cross-browser solution. First-party
popup storage and third-party iframe storage are not guaranteed to be
shared, so the iframe can finish popup auth and still fail to see any
stored controller/session state.

`postMessage` handoff is the most reliable fix because it does not
depend on shared storage between the popup and the iframe.

## What Changed

### Popup trigger behavior

- keep automatic detection for restrictive iframe environments
- keep the explicit `webauthnPopup` override for development/testing
- restrict popup auth to WebAuthn only; other signers continue in the
iframe

### Popup auth flow

- keep `/auth` as the standalone popup route
- replace popup actions with explicit WebAuthn flows:
  - `signup`
  - `login`
- keep signup/login + requested session creation in the same popup
- keep popup close/ack handling over `postMessage`

### Popup completion handoff

- replace the old popup result shape with exported controller/session
state
- send the popup result back to the opener via
`window.opener.postMessage(...)`
- import the returned controller/session state into the iframe instead
of calling `Controller.fromStore()` after popup completion

### Controller/session restore

- add controller wrapper helpers for:
  - metadata import
  - session import
  - popup state export/import
- reuse those helpers for both:
  - WebAuthn signup/login popup completion
  - WebAuthn-backed session creation popup completion

### Connect flow cleanup

- remove the popup flow’s dependency on shared popup local storage
- stop bootstrapping popup `/auth` from stored controller state
- keep the normal iframe method drawer for non-WebAuthn auth methods
- make popup signup/login action handling explicit so popup auth does
not silently switch between account creation and login

## Result

For restrictive iframe environments:

- WebAuthn can leave the iframe and run in a popup
- signup can create the account and requested session in the same popup
- login can authenticate and create the requested session in the same
popup
- popup completion no longer depends on shared browser storage
- iframe restores the returned controller/session state locally

## Manual Validation

- Safari restrictive iframe signup via passkey completes in one popup
and returns successfully
- Safari restrictive iframe login via passkey completes in one popup and
returns successfully
- no duplicate session popup appears after popup completion
- no popup flow depends on `Controller.fromStore()` after completion

## Testing

- `pnpm format --filter @cartridge/keychain`
- repo pre-commit checks reached lint/tests/build and failed only at
`graphql:gen` because `api.cartridge.gg` could not be resolved from this
environment

Author: broody

examples/next/src/components/providers/StarknetProvider.tsx

@@ -213,7 +213,6 @@ export const controllerConnector = new ControllerConnector({
   tokens: {
     erc20: ["lords", "strk"],
   },
-
   // nums (achievements, quests)
   // slot: "nums-bal",
   // namespace: "NUMS",
@@ -230,9 +229,6 @@ export const controllerConnector = new ControllerConnector({
   // preset: "loot-survivor",
 
   // Summit (no achievements, no quests)
-  namespace: "relayer_0_0_1",
-  slot: "pg-mainnet-10",
-  preset: "savage-summit",
 });
 
 const session = new SessionConnector({

packages/controller/src/controller.ts

@@ -309,8 +309,9 @@ export default class ControllerProvider extends BaseProvider {
         return this.account;
       }
 
-      // Only open modal if NOT headless
-      this.iframes.keychain.open();
+      if (!headless) {
+        this.iframes.keychain.open();
+      }
 
       // Use connect() parameter if provided, otherwise fall back to constructor options
       const effectiveOptions = Array.isArray(options)
@@ -353,7 +354,6 @@ export default class ControllerProvider extends BaseProvider {
       }
       console.log(e);
     } finally {
-      // Only close modal if it was opened (not headless)
       if (!headless) {
         this.iframes.keychain.close();
       }

packages/controller/src/iframe/keychain.ts

@@ -40,6 +40,7 @@ export class KeychainIFrame extends IFrame<Keychain> {
     encryptedBlob,
     propagateSessionErrors,
     errorDisplayMode,
+    webauthnPopup,
     ...iframeOptions
   }: KeychainIframeOptions) {
     let onStarterpackPlayHandler: (() => Promise<void>) | undefined;
@@ -101,6 +102,10 @@ export class KeychainIFrame extends IFrame<Keychain> {
       _url.searchParams.set("should_override_preset_policies", "true");
     }
 
+    if (webauthnPopup) {
+      _url.searchParams.set("webauthn_popup", "true");
+    }
+
     // Policy precedence logic:
     // 1. If shouldOverridePresetPolicies is true and policies are provided, use policies
     // 2. Otherwise, if preset is defined, ignore provided policies

packages/controller/src/types.ts

@@ -259,6 +259,8 @@ export type KeychainOptions = IFrameOptions & {
   tokens?: Tokens;
   /** When true, defer iframe mounting until connect() is called. Reduces initial load and resource fetching. */
   lazyload?: boolean;
+  /** When true, force WebAuthn operations to run in a popup window instead of the iframe. Useful for development and testing. */
+  webauthnPopup?: boolean;
 };
 
 export type ProfileContextTypeVariant =

packages/keychain/src/components/ConnectRoute.test.tsx

@@ -27,9 +27,42 @@ const mockController = {
   chainId: vi.fn().mockReturnValue("SN_SEPOLIA"),
 };
 
+const defaultConnection = {
+  controller: mockController,
+  policies: null,
+  isPoliciesResolved: true,
+  verified: true,
+  origin: "https://test.app",
+  webauthnPopup: {
+    create: false,
+    get: false,
+  },
+  theme: {
+    name: "TestApp",
+    verified: true,
+  },
+};
+
 const mockUseConnection = vi.fn();
 vi.mock("@/hooks/connection", () => ({
-  useConnection: () => mockUseConnection(),
+  useConnection: () => {
+    const override = mockUseConnection() ?? {};
+    return {
+      ...defaultConnection,
+      ...override,
+      theme: {
+        ...defaultConnection.theme,
+        ...(override.theme ?? {}),
+      },
+      webauthnPopup:
+        typeof override.webauthnPopup === "object"
+          ? {
+              ...defaultConnection.webauthnPopup,
+              ...override.webauthnPopup,
+            }
+          : defaultConnection.webauthnPopup,
+    };
+  },
 }));
 
 const mockCleanupCallbacks = vi.fn();
@@ -86,17 +119,7 @@ describe("ConnectRoute", () => {
     mockLocation.search = "";
     // mockSnapshotLocalStorageToCookie.mockResolvedValue("mock-encrypted-blob");
 
-    mockUseConnection.mockReturnValue({
-      controller: mockController,
-      policies: null,
-      isPoliciesResolved: true,
-      verified: true,
-      origin: "https://test.app",
-      theme: {
-        name: "TestApp",
-        verified: true,
-      },
-    });
+    mockUseConnection.mockReturnValue({});
   });
 
   describe("Embedded mode (iframe)", () => {
@@ -167,8 +190,8 @@ describe("ConnectRoute", () => {
 
       renderWithProviders(<ConnectRoute />);
 
-      // Should render CreateSession component
-      expect(screen.getByText("Create Session")).toBeInTheDocument();
+      expect(mockParams.resolve).not.toHaveBeenCalled();
+      expect(mockSafeRedirect).not.toHaveBeenCalled();
     });
 
     it("does not show UI for verified policies without approvals", () => {
@@ -314,9 +337,7 @@ describe("ConnectRoute", () => {
         initialUrl: "/?redirect_url=https://example.com/callback",
       });
 
-      // Should show CreateSession UI instead of redirecting immediately
-      expect(screen.getByText("Create Session")).toBeInTheDocument();
-      // No immediate redirect for unverified policies
+      expect(mockParams.resolve).not.toHaveBeenCalled();
       expect(mockSafeRedirect).not.toHaveBeenCalled();
     });