feat: add headless mode support to controller SDK

.claude/settings.json

@@ -17,6 +17,7 @@
       "Bash(pnpm:storybook:*)",
       "Bash(pnpm:e2e:*)",
       "Bash(pnpm:--filter:*)",
+      "Bash(gh:pr:*)",
       "Bash(git:status)",
       "Bash(git:diff)",
       "Bash(git:log)",

.gitignore

@@ -55,6 +55,7 @@ htmlcov/
 .cache
 nosetests.xml
 coverage.xml
+**/coverage/
 *.cover
 *.py,cover
 .hypothesis/

examples/next/src/components/Header.tsx

@@ -13,6 +13,9 @@ import { useState, useEffect, useRef, useMemo } from "react";
 import { constants, num, shortString } from "starknet";
 import { Chain } from "@starknet-react/chains";
 import SessionConnector from "@cartridge/connector/session";
+import { HeadlessLogin } from "components/HeadlessLogin";
+
+type HeadlessModalState = "closed" | "open" | "hidden";
 
 const Header = () => {
   const { connect, connectors } = useConnect();
@@ -21,6 +24,8 @@ const Header = () => {
   const { address, status } = useAccount();
   const [networkOpen, setNetworkOpen] = useState(false);
   const [profileOpen, setProfileOpen] = useState(false);
+  const [headlessState, setHeadlessState] =
+    useState<HeadlessModalState>("closed");
   const [isControllerReady, setIsControllerReady] = useState(false);
   const { switchChain } = useSwitchChain({
     params: {
@@ -188,6 +193,12 @@ const Header = () => {
           >
             Standalone
           </Button>
+          <Button
+            onClick={() => setHeadlessState("open")}
+            disabled={!isControllerReady}
+          >
+            Headless
+          </Button>
           <Button
             onClick={() => {
               connect({ connector: controllerConnector });
@@ -217,6 +228,35 @@ const Header = () => {
           )}
         </div>
       )}
+
+      {headlessState !== "closed" && (
+        <div
+          className={
+            headlessState === "open"
+              ? "fixed inset-0 z-[9999] flex items-center justify-center bg-black/60 p-4"
+              : "hidden"
+          }
+          onClick={() => setHeadlessState("closed")}
+        >
+          <div
+            className="relative w-full max-w-xl"
+            onClick={(event) => event.stopPropagation()}
+          >
+            <button
+              type="button"
+              onClick={() => setHeadlessState("closed")}
+              className="absolute -top-3 -right-3 rounded-full bg-white px-3 py-1 text-sm font-medium text-gray-700 shadow hover:bg-gray-100"
+            >
+              Close
+            </button>
+            <HeadlessLogin
+              onStart={() => setHeadlessState("hidden")}
+              onDone={() => setHeadlessState("closed")}
+              onError={() => setHeadlessState("open")}
+            />
+          </div>
+        </div>
+      )}
     </div>
   );
 };

examples/next/src/components/HeadlessLogin.tsx

@@ -0,0 +1,231 @@
+"use client";
+
+import { useConnect } from "@starknet-react/core";
+import { useState } from "react";
+import { controllerConnector } from "./providers/StarknetProvider";
+
+type AuthMethod = "passkey" | "metamask";
+
+interface EthereumProvider {
+  request: (args: { method: string; params?: unknown[] }) => Promise<unknown>;
+  isMetaMask?: boolean;
+}
+
+export function HeadlessLogin({
+  onStart,
+  onDone,
+  onError,
+}: {
+  onStart?: () => void;
+  onDone?: () => void;
+  onError?: () => void;
+}) {
+  const { connectAsync } = useConnect();
+  const [username, setUsername] = useState("");
+  const [loading, setLoading] = useState<AuthMethod | null>(null);
+  const [result, setResult] = useState<{
+    success: boolean;
+    message: string;
+    address?: string;
+  } | null>(null);
+  const prepareHeadlessConnect = async () => {
+    const controller = controllerConnector.controller;
+    // Ensure we don't short-circuit on an existing account.
+    if (controller.account) {
+      await controller.disconnect();
+    }
+    return controller;
+  };
+
+  const handlePasskeyLogin = async () => {
+    if (!username) {
+      setResult({
+        success: false,
+        message: "Please provide a username",
+      });
+      return;
+    }
+
+    onStart?.();
+    setLoading("passkey");
+    setResult(null);
+
+    try {
+      const controller = await prepareHeadlessConnect();
+      const account = await controller.connect({
+        username,
+        signer: "webauthn",
+      });
+      if (!account) {
+        throw new Error("Failed to connect");
+      }
+
+      // Sync starknet-react state so the header/app reflect the new connection.
+      await connectAsync({ connector: controllerConnector });
+
+      setResult({
+        success: true,
+        message: "Successfully authenticated with Passkey!",
+        address: account.address,
+      });
+      onDone?.();
+    } catch (error: unknown) {
+      setResult({
+        success: false,
+        message: (error as Error)?.message || "Passkey authentication failed",
+      });
+      onError?.();
+    } finally {
+      setLoading(null);
+    }
+  };
+
+  const handleMetaMaskLogin = async () => {
+    if (!username) {
+      setResult({
+        success: false,
+        message: "Please provide a username",
+      });
+      return;
+    }
+
+    onStart?.();
+    setLoading("metamask");
+    setResult(null);
+
+    try {
+      // Check if MetaMask is installed
+      const ethereum = (window as { ethereum?: EthereumProvider }).ethereum;
+      if (!ethereum) {
+        setResult({
+          success: false,
+          message: "MetaMask is not installed",
+        });
+        onError?.();
+        return;
+      }
+
+      const controller = await prepareHeadlessConnect();
+      const account = await controller.connect({
+        username,
+        signer: "metamask",
+      });
+      if (!account) {
+        throw new Error("Failed to connect");
+      }
+
+      // Sync starknet-react state so the header/app reflect the new connection.
+      await connectAsync({ connector: controllerConnector });
+
+      setResult({
+        success: true,
+        message: "Successfully authenticated with MetaMask!",
+        address: account.address,
+      });
+      onDone?.();
+    } catch (error: unknown) {
+      setResult({
+        success: false,
+        message: (error as Error)?.message || "MetaMask authentication failed",
+      });
+      onError?.();
+    } finally {
+      setLoading(null);
+    }
+  };
+
+  return (
+    <div className="space-y-4 rounded-lg border border-gray-200 bg-white p-6 dark:border-gray-700 dark:bg-gray-800">
+      <h3 className="text-lg font-semibold text-gray-900 dark:text-white">
+        Headless Login
+      </h3>
+
+      <p className="text-sm text-gray-600 dark:text-gray-400">
+        Test programmatic authentication without UI. This demonstrates the
+        headless mode feature for automated authentication with Passkey or
+        MetaMask.
+      </p>
+
+      <div className="space-y-3">
+        <div>
+          <label
+            htmlFor="headless-username"
+            className="mb-1 block text-sm font-medium text-gray-700 dark:text-gray-300"
+          >
+            Username
+          </label>
+          <input
+            id="headless-username"
+            type="text"
+            value={username}
+            onChange={(e) => setUsername(e.target.value)}
+            placeholder="Enter username"
+            className="w-full rounded-md border border-gray-300 bg-white px-3 py-2 text-sm text-gray-900 placeholder-gray-400 focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500 dark:border-gray-600 dark:bg-gray-700 dark:text-white dark:placeholder-gray-500"
+            disabled={loading !== null}
+          />
+        </div>
+
+        <div className="flex gap-3">
+          <button
+            onClick={handlePasskeyLogin}
+            disabled={loading !== null || !username}
+            className="flex-1 rounded-md bg-purple-600 px-4 py-2 text-sm font-medium text-white transition-colors hover:bg-purple-700 focus:outline-none focus:ring-2 focus:ring-purple-500 focus:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 dark:bg-purple-500 dark:hover:bg-purple-600"
+          >
+            {loading === "passkey" ? "Authenticating..." : "Login with Passkey"}
+          </button>
+
+          <button
+            onClick={handleMetaMaskLogin}
+            disabled={loading !== null || !username}
+            className="flex-1 rounded-md bg-orange-600 px-4 py-2 text-sm font-medium text-white transition-colors hover:bg-orange-700 focus:outline-none focus:ring-2 focus:ring-orange-500 focus:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 dark:bg-orange-500 dark:hover:bg-orange-600"
+          >
+            {loading === "metamask"
+              ? "Authenticating..."
+              : "Login with MetaMask"}
+          </button>
+        </div>
+      </div>
+
+      {result && (
+        <div
+          className={`mt-4 rounded-md p-4 ${
+            result.success
+              ? "bg-green-50 text-green-800 dark:bg-green-900/20 dark:text-green-400"
+              : "bg-red-50 text-red-800 dark:bg-red-900/20 dark:text-red-400"
+          }`}
+        >
+          <p className="text-sm font-medium">
+            {result.success ? "✓ Success" : "✗ Error"}
+          </p>
+          <p className="mt-1 text-sm">{result.message}</p>
+          {result.address && (
+            <p className="mt-2 break-all font-mono text-xs">
+              Address: {result.address}
+            </p>
+          )}
+        </div>
+      )}
+
+      <div className="mt-4 space-y-2 rounded-md bg-blue-50 p-4 dark:bg-blue-900/20">
+        <p className="text-xs text-blue-800 dark:text-blue-400">
+          <strong>Passkey Authentication:</strong> Uses the passkey signer
+          already registered for this username. Make sure the account has a
+          WebAuthn signer before testing.
+        </p>
+        <p className="text-xs text-blue-800 dark:text-blue-400">
+          <strong>MetaMask Authentication:</strong> Requires MetaMask browser
+          extension to be installed. Will prompt for account connection when
+          clicked.
+        </p>
+        <p className="text-xs text-blue-800 dark:text-blue-400">
+          <strong>Note:</strong> Headless mode auto-submits login. With no
+          policies, sign-in completes without session approval UI. If policies
+          are unverified or include approvals, Keychain will prompt for session
+          approval after authentication; verified policies auto-create the
+          session. Use <code>connect({"{ username, signer }"})</code> and pass{" "}
+          <code>password</code> when using the password signer.
+        </p>
+      </div>
+    </div>
+  );
+}

examples/next/src/components/Starterpack.tsx

@@ -3,7 +3,7 @@
 import { useAccount, useNetwork } from "@starknet-react/core";
 import ControllerConnector from "@cartridge/connector/controller";
 import { Button, Input } from "@cartridge/ui";
-import { useState, useEffect, useRef } from "react";
+import { useState, useEffect, useMemo, useRef, useCallback } from "react";
 import { constants, num } from "starknet";
 
 export const Starterpack = () => {
@@ -12,7 +12,7 @@ export const Starterpack = () => {
 
   const controllerConnector = connector as unknown as ControllerConnector;
 
-  const getDefaultStarterpackIds = () => {
+  const getDefaultStarterpackIds = useCallback(() => {
     if (chain && num.toHex(chain.id) === constants.StarknetChainId.SN_MAIN) {
       return {
         purchaseOnchain: 0,
@@ -23,9 +23,12 @@ export const Starterpack = () => {
       purchaseOnchain: 0,
       claim: "claim-dopewars-sepolia",
     };
-  };
+  }, [chain]);
 
-  const defaultIds = getDefaultStarterpackIds();
+  const defaultIds = useMemo(
+    () => getDefaultStarterpackIds(),
+    [getDefaultStarterpackIds],
+  );
   const [claimSpId, setClaimSpId] = useState<string>(defaultIds.claim);
   const [claimPreimage, setClaimPreimage] = useState<string>("");
   const [purchaseOnchainSpId, setPurchaseOnchainSpId] = useState<number>(
@@ -59,7 +62,7 @@ export const Starterpack = () => {
     // Update our references after successful comparison and update
     expectedDefaultsRef.current = newDefaults;
     previousChainRef.current = chain;
-  }, [chain]);
+  }, [chain, getDefaultStarterpackIds]);
 
   if (!account) {
     return null;