@cartridge/controller 0.13.3 → 0.13.5

package/dist/types.d.ts

@@ -79,7 +79,7 @@ type CartridgeID = string;
 export type ControllerAccounts = Record<ContractAddress, CartridgeID>;
 export interface Keychain {
     probe(rpcUrl: string): Promise<ProbeReply | ConnectError>;
-    connect(signupOptions?: AuthOptions): Promise<ConnectReply | ConnectError>;
+    connect(options?: ConnectOptions): Promise<ConnectReply | ConnectError>;
     disconnect(): void;
     reset(): void;
     revoke(origin: string): void;
@@ -172,4 +172,23 @@ export type StarterpackOptions = {
     /** Callback fired after the Play button closes the starterpack modal */
     onPurchaseComplete?: () => void;
 };
+export interface ConnectOptions {
+    /** Signup options (shown in UI when not headless) */
+    signupOptions?: AuthOptions;
+    /** Headless mode username (when combined with signer) */
+    username?: string;
+    /** Headless mode signer option (auth method) */
+    signer?: AuthOption;
+    /** Required when signer is "password" */
+    password?: string;
+}
+export type HeadlessConnectOptions = Required<Pick<ConnectOptions, "username" | "signer">> & Pick<ConnectOptions, "password">;
+export type HeadlessConnectReply = {
+    code: ResponseCodes.SUCCESS;
+    address: string;
+} | {
+    code: ResponseCodes.USER_INTERACTION_REQUIRED;
+    requestId: string;
+    message?: string;
+} | ConnectError;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cartridge/controller",
-  "version": "0.13.3",
+  "version": "0.13.5",
   "description": "Cartridge Controller",
   "repository": {
     "type": "git",
@@ -10,17 +10,6 @@
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
-  "scripts": {
-    "build:deps": "pnpm build",
-    "dev": "vite build --watch",
-    "build:browser": "vite build",
-    "build:node": "tsup --config tsup.node.config.ts",
-    "build": "pnpm build:browser && pnpm build:node",
-    "format": "prettier --write \"src/**/*.ts\"",
-    "format:check": "prettier --check \"src/**/*.ts\"",
-    "test": "jest",
-    "version": "pnpm pkg get version"
-  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -37,11 +26,12 @@
     }
   },
   "dependencies": {
-    "@cartridge/controller-wasm": "catalog:",
-    "@cartridge/penpal": "catalog:",
+    "@cartridge/controller-wasm": "0.9.3",
+    "@cartridge/penpal": "^6.2.4",
     "micro-sol-signer": "^0.5.0",
     "bs58": "^6.0.0",
     "ethers": "^6.13.5",
+    "@starknet-io/get-starknet-wallet-standard": "5.0.0-beta.0",
     "@starknet-io/types-js": "0.9.1",
     "@telegram-apps/sdk": "^2.4.0",
     "@turnkey/sdk-browser": "^4.0.0",
@@ -52,20 +42,31 @@
     "@walletconnect/ethereum-provider": "^2.20.0"
   },
   "devDependencies": {
-    "@cartridge/tsconfig": "workspace:*",
-    "@types/jest": "catalog:",
-    "@types/mocha": "catalog:",
-    "@types/node": "catalog:",
+    "@types/jest": "^29.5.14",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^18.0.6",
     "jest": "^29.7.0",
-    "prettier": "catalog:",
+    "prettier": "^3.4.2",
     "rollup-plugin-visualizer": "^5.12.0",
     "ts-jest": "^29.2.5",
-    "tsup": "catalog:",
-    "typescript": "catalog:",
-    "vite": "catalog:",
+    "tsup": "^8.0.1",
+    "typescript": "^5.7.3",
+    "vite": "^6.0.0",
     "vite-plugin-dts": "^4.5.3",
     "vite-plugin-node-polyfills": "^0.23.0",
-    "vite-plugin-top-level-await": "catalog:",
-    "vite-plugin-wasm": "catalog:"
+    "vite-plugin-top-level-await": "^1.4.4",
+    "vite-plugin-wasm": "^3.4.1",
+    "@cartridge/tsconfig": "0.13.5"
+  },
+  "scripts": {
+    "build:deps": "pnpm build",
+    "dev": "vite build --watch",
+    "build:browser": "vite build",
+    "build:node": "tsup --config tsup.node.config.ts",
+    "build": "pnpm build:browser && pnpm build:node",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "test": "jest",
+    "version": "pnpm pkg get version"
   }
-}
+}

package/src/__tests__/asWalletStandard.test.ts

@@ -0,0 +1,87 @@
+import ControllerProvider from "../controller";
+
+// Mock StarknetInjectedWallet
+const mockInnerDisconnect = jest.fn().mockResolvedValue(undefined);
+const mockFeatures = {
+  "standard:connect": { version: "1.0.0", connect: jest.fn() },
+  "standard:disconnect": {
+    version: "1.0.0",
+    disconnect: mockInnerDisconnect,
+  },
+  "standard:events": { version: "1.0.0", on: jest.fn() },
+  "starknet:walletApi": { version: "1.0.0", request: jest.fn() },
+};
+
+jest.mock("@starknet-io/get-starknet-wallet-standard", () => ({
+  StarknetInjectedWallet: jest.fn().mockImplementation(() => ({
+    version: "1.0.0",
+    name: "Controller",
+    icon: "data:image/svg+xml,<svg/>",
+    chains: ["starknet:mainnet"],
+    accounts: [],
+    features: mockFeatures,
+  })),
+}));
+
+describe("asWalletStandard", () => {
+  let controller: ControllerProvider;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    console.warn = jest.fn();
+    console.error = jest.fn();
+    controller = new ControllerProvider({});
+  });
+
+  test("should delegate properties from inner wallet", () => {
+    const wallet = controller.asWalletStandard();
+
+    expect(wallet.version).toBe("1.0.0");
+    expect(wallet.name).toBe("Controller");
+    expect(wallet.chains).toEqual(["starknet:mainnet"]);
+    expect(wallet.accounts).toEqual([]);
+  });
+
+  test("should forward non-disconnect features from inner wallet", () => {
+    const wallet = controller.asWalletStandard();
+
+    expect(wallet.features["standard:connect"]).toBe(
+      mockFeatures["standard:connect"],
+    );
+    expect(wallet.features["standard:events"]).toBe(
+      mockFeatures["standard:events"],
+    );
+    expect(wallet.features["starknet:walletApi"]).toBe(
+      mockFeatures["starknet:walletApi"],
+    );
+  });
+
+  test("should call controller.disconnect when wallet standard disconnect is called", async () => {
+    const wallet = controller.asWalletStandard();
+    const controllerDisconnect = jest
+      .spyOn(controller, "disconnect")
+      .mockResolvedValue(undefined);
+
+    await wallet.features["standard:disconnect"].disconnect();
+
+    expect(mockInnerDisconnect).toHaveBeenCalled();
+    expect(controllerDisconnect).toHaveBeenCalled();
+  });
+
+  test("should call inner disconnect before controller disconnect", async () => {
+    const callOrder: string[] = [];
+
+    mockInnerDisconnect.mockImplementation(async () => {
+      callOrder.push("inner");
+    });
+
+    jest.spyOn(controller, "disconnect").mockImplementation(async () => {
+      callOrder.push("controller");
+    });
+
+    const wallet = controller.asWalletStandard();
+    await wallet.features["standard:disconnect"].disconnect();
+
+    expect(callOrder).toEqual(["inner", "controller"]);
+  });
+});

package/src/__tests__/headlessConnectApproval.test.ts

@@ -0,0 +1,97 @@
+import { ResponseCodes } from "../types";
+
+let iframeOpen: jest.Mock | undefined;
+
+// Mock the KeychainIFrame so we can manually trigger onSessionCreated.
+jest.mock("../iframe/keychain", () => ({
+  KeychainIFrame: jest.fn().mockImplementation((_opts: any) => {
+    iframeOpen = jest.fn();
+    return {
+      open: iframeOpen,
+      close: jest.fn(),
+    };
+  }),
+}));
+
+// Keep ControllerAccount lightweight for this test.
+jest.mock("../account", () => ({
+  __esModule: true,
+  default: jest
+    .fn()
+    .mockImplementation(
+      (
+        _provider: unknown,
+        _rpcUrl: string,
+        address: string,
+        _keychain: unknown,
+        _options: unknown,
+      ) => ({
+        address,
+      }),
+    ),
+}));
+
+import ControllerProvider from "../controller";
+
+describe("headless connect requiring approval", () => {
+  test("does not open UI and resolves connect() only after keychain.connect()", async () => {
+    const controller = new ControllerProvider();
+
+    let resolveConnect: ((value: any) => void) | undefined;
+    const connectPromise = new Promise((resolve) => {
+      resolveConnect = resolve;
+    });
+
+    const keychain = {
+      connect: jest.fn().mockReturnValue(connectPromise),
+      disconnect: jest.fn(),
+      reset: jest.fn(),
+    } as any;
+
+    // Avoid waiting for Penpal connection in this unit test.
+    (controller as any).keychain = keychain;
+    (controller as any).waitForKeychain = () => Promise.resolve();
+
+    const accountsChanged = jest.fn();
+    controller.on("accountsChanged", accountsChanged as any);
+
+    const controllerConnectPromise = controller.connect({
+      username: "alice",
+      signer: "webauthn",
+    });
+
+    let resolved = false;
+    void controllerConnectPromise.then(() => {
+      resolved = true;
+    });
+
+    // Flush microtasks for:
+    // 1) await waitForKeychain()
+    // 2) await keychain.connect(...)
+    await Promise.resolve();
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(keychain.connect).toHaveBeenCalledWith({
+      username: "alice",
+      signer: "webauthn",
+      password: undefined,
+    });
+    expect(iframeOpen).not.toHaveBeenCalled();
+    expect(resolved).toBe(false);
+
+    resolveConnect?.({
+      code: ResponseCodes.SUCCESS,
+      address: "0xabc",
+    });
+
+    const account = await controllerConnectPromise;
+    expect(account?.address).toBe("0xabc");
+    expect(accountsChanged).toHaveBeenCalledWith(["0xabc"]);
+
+    // Subsequent connect() should short-circuit (no second approval flow).
+    const account2 = await controller.connect();
+    expect(account2?.address).toBe("0xabc");
+    expect(keychain.connect).toHaveBeenCalledTimes(1);
+  });
+});

package/src/__tests__/iframeSecurity.test.ts

@@ -0,0 +1,84 @@
+import {
+  buildIframeAllowList,
+  isLocalhostHostname,
+  validateKeychainIframeUrl,
+} from "../iframe/security";
+
+describe("iframe security", () => {
+  describe("isLocalhostHostname", () => {
+    it("returns true for localhost hosts", () => {
+      expect(isLocalhostHostname("localhost")).toBe(true);
+      expect(isLocalhostHostname("app.localhost")).toBe(true);
+      expect(isLocalhostHostname("127.0.0.1")).toBe(true);
+      expect(isLocalhostHostname("[::1]")).toBe(true);
+      expect(isLocalhostHostname("::1")).toBe(true);
+    });
+
+    it("returns false for non-local hosts", () => {
+      expect(isLocalhostHostname("example.com")).toBe(false);
+      expect(isLocalhostHostname("localhost.example.com")).toBe(false);
+    });
+  });
+
+  describe("validateKeychainIframeUrl", () => {
+    it("allows https URLs", () => {
+      expect(() =>
+        validateKeychainIframeUrl(new URL("https://x.cartridge.gg")),
+      ).not.toThrow();
+    });
+
+    it("allows localhost http URLs for development", () => {
+      expect(() =>
+        validateKeychainIframeUrl(new URL("http://localhost:3001")),
+      ).not.toThrow();
+      expect(() =>
+        validateKeychainIframeUrl(new URL("http://127.0.0.1:3001")),
+      ).not.toThrow();
+      expect(() =>
+        validateKeychainIframeUrl(new URL("http://[::1]:3001")),
+      ).not.toThrow();
+    });
+
+    it("rejects insecure remote http URLs", () => {
+      expect(() =>
+        validateKeychainIframeUrl(new URL("http://evil.example")),
+      ).toThrow(
+        "Invalid keychain iframe URL: only https:// or local http:// URLs are allowed",
+      );
+    });
+
+    it("rejects non-http(s) protocols", () => {
+      expect(() =>
+        validateKeychainIframeUrl(new URL("javascript:alert(1)")),
+      ).toThrow(
+        "Invalid keychain iframe URL: only https:// or local http:// URLs are allowed",
+      );
+
+      expect(() =>
+        validateKeychainIframeUrl(new URL("data:text/html,<h1>xss</h1>")),
+      ).toThrow(
+        "Invalid keychain iframe URL: only https:// or local http:// URLs are allowed",
+      );
+    });
+
+    it("rejects credentialed URLs", () => {
+      expect(() =>
+        validateKeychainIframeUrl(new URL("https://user:pass@x.cartridge.gg")),
+      ).toThrow("Invalid keychain iframe URL: credentials are not allowed");
+    });
+  });
+
+  describe("buildIframeAllowList", () => {
+    it("does not include local-network-access for remote URLs", () => {
+      const allowList = buildIframeAllowList(new URL("https://x.cartridge.gg"));
+      expect(allowList).toContain("publickey-credentials-create *");
+      expect(allowList).toContain("payment *");
+      expect(allowList).not.toContain("local-network-access *");
+    });
+
+    it("includes local-network-access for localhost development URLs", () => {
+      const allowList = buildIframeAllowList(new URL("http://localhost:3001"));
+      expect(allowList).toContain("local-network-access *");
+    });
+  });
+});

package/src/__tests__/parseChainId.test.ts

@@ -44,7 +44,7 @@ describe("parseChainId", () => {
 
   describe("Non-Cartridge hosts", () => {
     test("returns placeholder chainId in Node", () => {
-      expect(parseChainId(new URL("http://dl:123123"))).toBe(
+      expect(parseChainId(new URL("http://dl:1234"))).toBe(
         shortString.encodeShortString("LOCALHOST"),
       );
     });

package/src/controller.ts

@@ -1,6 +1,8 @@
 import { AsyncMethodReturns } from "@cartridge/penpal";
 
 import { Policy } from "@cartridge/presets";
+import { StarknetInjectedWallet } from "@starknet-io/get-starknet-wallet-standard";
+import type { WalletWithStarknetFeatures } from "@starknet-io/get-starknet-wallet-standard/features";
 import {
   AddInvokeTransactionResult,
   AddStarknetChainParameters,
@@ -10,7 +12,7 @@ import { constants, shortString, WalletAccount } from "starknet";
 import { version } from "../package.json";
 import ControllerAccount from "./account";
 import { KEYCHAIN_URL } from "./constants";
-import { NotReadyToConnect } from "./errors";
+import { HeadlessAuthenticationError, NotReadyToConnect } from "./errors";
 import { KeychainIFrame } from "./iframe";
 import BaseProvider from "./provider";
 import {
@@ -18,6 +20,7 @@ import {
   Chain,
   ConnectError,
   ConnectReply,
+  ConnectOptions,
   ControllerOptions,
   IFrames,
   Keychain,
@@ -226,8 +229,18 @@ export default class ControllerProvider extends BaseProvider {
   }
 
   async connect(
-    signupOptions?: AuthOptions,
+    options?: AuthOptions | ConnectOptions,
   ): Promise<WalletAccount | undefined> {
+    const connectOptions = Array.isArray(options) ? undefined : options;
+    const headless =
+      connectOptions?.username && connectOptions?.signer
+        ? {
+            username: connectOptions.username,
+            signer: connectOptions.signer,
+            password: connectOptions.password,
+          }
+        : undefined;
+
     if (!this.iframes) {
       return;
     }
@@ -239,21 +252,73 @@ export default class ControllerProvider extends BaseProvider {
     // Ensure iframe is created if using lazy loading
     if (!this.iframes.keychain) {
       this.iframes.keychain = this.createKeychainIframe();
-      // Wait for the keychain to be ready
-      await this.waitForKeychain();
     }
 
+    // Always wait for the keychain connection to be established
+    await this.waitForKeychain();
+
     if (!this.keychain || !this.iframes.keychain) {
       console.error(new NotReadyToConnect().message);
       return;
     }
 
-    this.iframes.keychain.open();
-
     try {
+      if (headless) {
+        // Headless auth should not open the UI until the keychain determines
+        // user interaction is required (e.g. session approval).
+        const response = await this.keychain.connect({
+          username: headless.username,
+          signer: headless.signer,
+          password: headless.password,
+        });
+
+        if (response.code !== ResponseCodes.SUCCESS) {
+          throw new HeadlessAuthenticationError(
+            "message" in response && response.message
+              ? response.message
+              : "Headless authentication failed",
+          );
+        }
+
+        // Keychain will call onSessionCreated (awaitable) during headless connect,
+        // which probes and updates this.account. Keep a fallback for older keychains.
+        if (this.account) {
+          return this.account;
+        }
+
+        const address =
+          "address" in response && response.address ? response.address : null;
+        if (!address) {
+          throw new HeadlessAuthenticationError(
+            "Headless authentication failed",
+          );
+        }
+
+        this.account = new ControllerAccount(
+          this,
+          this.rpcUrl(),
+          address,
+          this.keychain,
+          this.options,
+          this.iframes.keychain,
+        );
+        this.emitAccountsChanged([address]);
+        return this.account;
+      }
+
+      // Only open modal if NOT headless
+      this.iframes.keychain.open();
+
       // Use connect() parameter if provided, otherwise fall back to constructor options
-      const effectiveOptions = signupOptions ?? this.options.signupOptions;
-      let response = await this.keychain.connect(effectiveOptions);
+      const effectiveOptions = Array.isArray(options)
+        ? options
+        : (connectOptions?.signupOptions ?? this.options.signupOptions);
+
+      // Pass options to keychain
+      let response = await this.keychain.connect({
+        signupOptions: effectiveOptions,
+      });
+
       if (response.code !== ResponseCodes.SUCCESS) {
         throw new Error(response.message);
       }
@@ -270,9 +335,25 @@ export default class ControllerProvider extends BaseProvider {
 
       return this.account;
     } catch (e) {
+      if (headless) {
+        if (e instanceof HeadlessAuthenticationError) {
+          throw e;
+        }
+
+        const message =
+          e instanceof Error
+            ? e.message
+            : typeof e === "object" && e && "message" in e
+              ? String((e as any).message)
+              : "Headless authentication failed";
+        throw new HeadlessAuthenticationError(message);
+      }
       console.log(e);
     } finally {
-      this.iframes.keychain.close();
+      // Only close modal if it was opened (not headless)
+      if (!headless) {
+        this.iframes.keychain.close();
+      }
     }
   }
 
@@ -306,12 +387,22 @@ export default class ControllerProvider extends BaseProvider {
   }
 
   async disconnect() {
+    this.account = undefined;
+    this.emitAccountsChanged([]);
+
+    try {
+      if (typeof localStorage !== "undefined") {
+        localStorage.removeItem("lastUsedConnector");
+      }
+    } catch {
+      // Ignore environments where localStorage is unavailable.
+    }
+
     if (!this.keychain) {
       console.error(new NotReadyToConnect().message);
       return;
     }
 
-    this.account = undefined;
     return this.keychain.disconnect();
   }
 
@@ -401,6 +492,13 @@ export default class ControllerProvider extends BaseProvider {
     this.keychain.openSettings();
   }
 
+  async close() {
+    if (!this.iframes || !this.iframes.keychain) {
+      return;
+    }
+    this.iframes.keychain.close();
+  }
+
   revoke(origin: string, _policy: Policy[]) {
     if (!this.keychain) {
       console.error(new NotReadyToConnect().message);
@@ -514,6 +612,54 @@ export default class ControllerProvider extends BaseProvider {
     return await this.keychain.delegateAccount();
   }
 
+  /**
+   * Returns a wallet standard interface for the controller.
+   * This allows using the controller with libraries that expect the wallet standard interface.
+   */
+  asWalletStandard(): WalletWithStarknetFeatures {
+    if (typeof window !== "undefined") {
+      console.warn(
+        `Casting Controller to WalletWithStarknetFeatures is an experimental feature. ` +
+          `Please report any issues at https://github.com/cartridge-gg/controller/issues`,
+      );
+    }
+
+    const controller = this;
+    const inner = new StarknetInjectedWallet(controller);
+
+    // Override disconnect to also disconnect controller
+    const disconnect = {
+      "standard:disconnect": {
+        version: "1.0.0" as const,
+        disconnect: async () => {
+          await inner.features["standard:disconnect"].disconnect();
+          await controller.disconnect();
+        },
+      },
+    };
+
+    return {
+      get version() {
+        return inner.version;
+      },
+      get name() {
+        return inner.name;
+      },
+      get icon() {
+        return inner.icon;
+      },
+      get chains() {
+        return inner.chains;
+      },
+      get accounts() {
+        return inner.accounts;
+      },
+      get features() {
+        return { ...inner.features, ...disconnect };
+      },
+    };
+  }
+
   /**
    * Opens the keychain in standalone mode (first-party context) for authentication.
    * This establishes first-party storage, enabling seamless iframe access across all games.
@@ -622,7 +768,9 @@ export default class ControllerProvider extends BaseProvider {
     const iframe = new KeychainIFrame({
       ...this.options,
       rpcUrl: this.rpcUrl(),
-      onClose: this.keychain?.reset,
+      onClose: () => {
+        this.keychain?.reset?.();
+      },
       onConnect: (keychain) => {
         this.keychain = keychain;
       },
@@ -633,8 +781,12 @@ export default class ControllerProvider extends BaseProvider {
       encryptedBlob: encryptedBlob ?? undefined,
       username: username,
       onSessionCreated: async () => {
-        // Re-probe to establish connection now that storage access is granted and session created
-        await this.probe();
+        const previousAddress = this.account?.address;
+        const account = await this.probe();
+
+        if (account?.address && account.address !== previousAddress) {
+          this.emitAccountsChanged([account.address]);
+        }
       },
     });