@cartridge/controller 0.13.7 → 0.13.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cartridge/controller",
-  "version": "0.13.7",
+  "version": "0.13.9",
   "description": "Cartridge Controller",
   "repository": {
     "type": "git",
@@ -26,7 +26,7 @@
     }
   },
   "dependencies": {
-    "@cartridge/controller-wasm": "0.9.3",
+    "@cartridge/controller-wasm": "0.9.4",
     "@cartridge/penpal": "^6.2.4",
     "micro-sol-signer": "^0.5.0",
     "bs58": "^6.0.0",
@@ -56,14 +56,13 @@
     "vite-plugin-node-polyfills": "^0.23.0",
     "vite-plugin-top-level-await": "^1.4.4",
     "vite-plugin-wasm": "^3.4.1",
-    "@cartridge/tsconfig": "0.13.7"
+    "@cartridge/tsconfig": "0.13.9"
   },
   "scripts": {
-    "build:deps": "pnpm build",
+    "build:deps": "pnpm build:browser && pnpm build:node",
     "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",

package/src/__tests__/disconnect.test.ts

@@ -0,0 +1,112 @@
+import ControllerProvider from "../controller";
+
+type MockStorage = {
+  [key: string]: string;
+};
+
+const createMockLocalStorage = () => {
+  const store: MockStorage = {};
+
+  return {
+    get length() {
+      return Object.keys(store).length;
+    },
+    clear: jest.fn(() => {
+      Object.keys(store).forEach((key) => {
+        delete store[key];
+      });
+    }),
+    getItem: jest.fn((key: string) => (key in store ? store[key] : null)),
+    setItem: jest.fn((key: string, value: string) => {
+      store[key] = String(value);
+    }),
+    removeItem: jest.fn((key: string) => {
+      delete store[key];
+    }),
+    key: jest.fn((index: number) => {
+      const keys = Object.keys(store);
+      return keys[index] || null;
+    }),
+  } as Storage;
+};
+
+describe("ControllerProvider.disconnect", () => {
+  const originalLocalStorage = (global as any).localStorage;
+
+  beforeEach(() => {
+    (global as any).localStorage = createMockLocalStorage();
+  });
+
+  afterEach(() => {
+    (global as any).localStorage = originalLocalStorage;
+    jest.restoreAllMocks();
+  });
+
+  test("cleans persisted connector/session localStorage keys", async () => {
+    const controller = new ControllerProvider({});
+    const keychainDisconnect = jest.fn().mockResolvedValue(undefined);
+    (controller as any).keychain = {
+      disconnect: keychainDisconnect,
+    };
+
+    localStorage.setItem("lastUsedConnector", "controller");
+    localStorage.setItem(
+      "@cartridge/account/0x40bda2fcd37963c0b8f951801c63a88132feb399dab0f5318245b2c59a553af/0x534e5f5345504f4c4941",
+      JSON.stringify({ Controller: {} }),
+    );
+    localStorage.setItem("@cartridge/active", JSON.stringify({ Active: {} }));
+    localStorage.setItem(
+      "@cartridge/https://x.cartridge.gg/active",
+      JSON.stringify({ Active: {} }),
+    );
+    localStorage.setItem(
+      "@cartridge/policies/0x4fdcb829582d172a6f3858b97c16da38b08da5a1df7101a5d285b868d89921b/0x534e5f4d41494e",
+      JSON.stringify({ policies: [] }),
+    );
+    localStorage.setItem("@cartridge/features", JSON.stringify({}));
+    localStorage.setItem(
+      "@cartridge/session/0x4fdcb829582d172a6f3858b97c16da38b08da5a1df7101a5d285b868d89921b/0x534e5f4d41494e",
+      JSON.stringify({ Session: {} }),
+    );
+    localStorage.setItem("keepMe", "keep");
+
+    await controller.disconnect();
+
+    expect(localStorage.getItem("lastUsedConnector")).toBeNull();
+    expect(
+      localStorage.getItem(
+        "@cartridge/account/0x40bda2fcd37963c0b8f951801c63a88132feb399dab0f5318245b2c59a553af/0x534e5f5345504f4c4941",
+      ),
+    ).toBeNull();
+    expect(localStorage.getItem("@cartridge/active")).toBeNull();
+    expect(
+      localStorage.getItem("@cartridge/https://x.cartridge.gg/active"),
+    ).toBeNull();
+    expect(
+      localStorage.getItem(
+        "@cartridge/policies/0x4fdcb829582d172a6f3858b97c16da38b08da5a1df7101a5d285b868d89921b/0x534e5f4d41494e",
+      ),
+    ).toBeNull();
+    expect(localStorage.getItem("@cartridge/features")).toBeNull();
+    expect(
+      localStorage.getItem(
+        "@cartridge/session/0x4fdcb829582d172a6f3858b97c16da38b08da5a1df7101a5d285b868d89921b/0x534e5f4d41494e",
+      ),
+    ).toBeNull();
+    expect(localStorage.getItem("keepMe")).toBe("keep");
+    expect(localStorage.removeItem).toHaveBeenCalledWith("lastUsedConnector");
+    expect(keychainDisconnect).toHaveBeenCalledTimes(1);
+  });
+
+  test("does not throw when localStorage is unavailable", async () => {
+    delete (global as any).localStorage;
+    const controller = new ControllerProvider({});
+    const keychainDisconnect = jest.fn().mockResolvedValue(undefined);
+    (controller as any).keychain = {
+      disconnect: keychainDisconnect,
+    };
+
+    await expect(controller.disconnect()).resolves.toBeUndefined();
+    expect(keychainDisconnect).toHaveBeenCalledTimes(1);
+  });
+});

package/src/constants.ts

@@ -1,3 +1,7 @@
 export const KEYCHAIN_URL = "https://x.cartridge.gg";
 export const PROFILE_URL = "https://profile.cartridge.gg";
 export const API_URL = "https://api.cartridge.gg";
+
+// Query parameter name used to pass session data via URL redirects.
+// Borrowed from Telegram mini app convention, but the choice is arbitrary.
+export const REDIRECT_QUERY_NAME = "startapp";

package/src/controller.ts

@@ -395,6 +395,13 @@ export default class ControllerProvider extends BaseProvider {
     try {
       if (typeof localStorage !== "undefined") {
         localStorage.removeItem("lastUsedConnector");
+
+        for (let i = localStorage.length - 1; i >= 0; i--) {
+          const key = localStorage.key(i);
+          if (key?.startsWith("@cartridge/")) {
+            localStorage.removeItem(key);
+          }
+        }
       }
     } catch {
       // Ignore environments where localStorage is unavailable.

package/src/iframe/keychain.ts

@@ -93,17 +93,24 @@ export class KeychainIFrame extends IFrame<Keychain> {
       _url.searchParams.set("username", encodeURIComponent(username));
     }
 
+    if (preset) {
+      _url.searchParams.set("preset", preset);
+    }
+
+    if (shouldOverridePresetPolicies) {
+      _url.searchParams.set("should_override_preset_policies", "true");
+    }
+
     // Policy precedence logic:
     // 1. If shouldOverridePresetPolicies is true and policies are provided, use policies
-    // 2. Otherwise, if preset is defined, use empty object (let preset take precedence)
-    // 3. Otherwise, use provided policies or empty object
+    // 2. Otherwise, if preset is defined, ignore provided policies
+    // 3. Otherwise, use provided policies
     if ((!preset || shouldOverridePresetPolicies) && policies) {
       _url.searchParams.set(
         "policies",
         encodeURIComponent(JSON.stringify(policies)),
       );
     } else if (preset) {
-      _url.searchParams.set("preset", preset);
       if (policies) {
         console.warn(
           "[Controller] Both `preset` and `policies` provided to ControllerProvider. " +

package/src/node/server.ts

@@ -1,5 +1,6 @@
 import * as http from "http";
 import { AddressInfo } from "net";
+import { REDIRECT_QUERY_NAME } from "../constants";
 
 type ServerResponse = http.ServerResponse<http.IncomingMessage> & {
   req: http.IncomingMessage;
@@ -38,7 +39,7 @@ export class CallbackServer {
     }
 
     const params = new URLSearchParams(req.url.split("?")[1]);
-    const session = params.get("startapp");
+    const session = params.get(REDIRECT_QUERY_NAME);
 
     if (!session) {
       console.warn("Received callback without session data");

package/src/session/provider.ts

@@ -7,7 +7,7 @@ import {
 import { loadConfig, SessionPolicies } from "@cartridge/presets";
 import { AddStarknetChainParameters } from "@starknet-io/types-js";
 import { encode } from "starknet";
-import { API_URL, KEYCHAIN_URL } from "../constants";
+import { API_URL, KEYCHAIN_URL, REDIRECT_QUERY_NAME } from "../constants";
 import { parsePolicies, ParsedSessionPolicies } from "../policies";
 import BaseProvider from "../provider";
 import { AuthOptions } from "../types";
@@ -50,12 +50,12 @@ export default class SessionProvider extends BaseProvider {
   protected _disconnectRedirectUrl?: string;
   protected _policies: ParsedSessionPolicies;
   protected _preset?: string;
-  private _ready: Promise<void>;
   protected _keychainUrl: string;
   protected _apiUrl: string;
   protected _publicKey!: string;
   protected _sessionKeyGuid!: string;
   protected _signupOptions?: AuthOptions;
+  private _readyPromise: Promise<void>;
   public reopenBrowser: boolean = true;
 
   constructor({
@@ -102,35 +102,23 @@ export default class SessionProvider extends BaseProvider {
     this._apiUrl = apiUrl ?? API_URL;
     this._signupOptions = signupOptions;
 
-    // Eagerly start async init: resolve preset policies (if any),
-    // then try to restore an existing session from storage.
-    // All public async methods await this before proceeding.
-    this._ready = this._init();
+    this._setSigningKeys();
+    this._readyPromise = this._resolvePreset();
 
     if (typeof window !== "undefined") {
       (window as any).starknet_controller_session = this;
     }
   }
 
-  private async _init(): Promise<void> {
-    if (this._preset) {
-      const config = await loadConfig(this._preset);
-      if (!config) {
-        throw new Error(`Failed to load preset: ${this._preset}`);
-      }
-
-      const sessionPolicies = getPresetSessionPolicies(config, this._chainId);
-      if (!sessionPolicies) {
-        throw new Error(
-          `No policies found for chain ${this._chainId} in preset ${this._preset}`,
-        );
-      }
-
-      this._policies = parsePolicies(sessionPolicies);
-    }
-
-    const account = this.tryRetrieveFromQueryOrStorage();
-    if (!account) {
+  private _setSigningKeys(): void {
+    const signerString = localStorage.getItem("sessionSigner");
+    if (signerString) {
+      const signer = JSON.parse(signerString);
+      this._publicKey = signer.pubKey;
+      this._sessionKeyGuid = signerToGuid({
+        starknet: { privateKey: encode.addHexPrefix(signer.privKey) },
+      });
+    } else {
       const pk = stark.randomAddress();
       this._publicKey = ec.starkCurve.getStarkKey(pk);
 
@@ -144,20 +132,27 @@ export default class SessionProvider extends BaseProvider {
       this._sessionKeyGuid = signerToGuid({
         starknet: { privateKey: encode.addHexPrefix(pk) },
       });
-    } else {
-      const pk = localStorage.getItem("sessionSigner");
-      if (!pk) throw new Error("failed to get sessionSigner");
+    }
+  }
 
-      const jsonPk: {
-        privKey: string;
-        pubKey: string;
-      } = JSON.parse(pk);
+  // Resolve preset policies asynchronously.
+  // Public methods await this before proceeding.
+  private async _resolvePreset(): Promise<void> {
+    if (!this._preset) return;
 
-      this._publicKey = jsonPk.pubKey;
-      this._sessionKeyGuid = signerToGuid({
-        starknet: { privateKey: encode.addHexPrefix(jsonPk.privKey) },
-      });
+    const config = await loadConfig(this._preset);
+    if (!config) {
+      throw new Error(`Failed to load preset: ${this._preset}`);
     }
+
+    const sessionPolicies = getPresetSessionPolicies(config, this._chainId);
+    if (!sessionPolicies) {
+      throw new Error(
+        `No policies found for chain ${this._chainId} in preset ${this._preset}`,
+      );
+    }
+
+    this._policies = parsePolicies(sessionPolicies);
   }
 
   private validatePoliciesSubset(
@@ -247,17 +242,31 @@ export default class SessionProvider extends BaseProvider {
   }
 
   async username() {
-    await this._ready;
+    await this._readyPromise;
+
+    if (!this.account) {
+      this.tryRetrieveSessionAccount();
+    }
+
     return this._username;
   }
 
   async probe(): Promise<WalletAccount | undefined> {
-    await this._ready;
+    await this._readyPromise;
+
+    if (!this.account) {
+      this.tryRetrieveSessionAccount();
+    }
+
     return this.account;
   }
 
   async connect(): Promise<WalletAccount | undefined> {
-    await this._ready;
+    await this._readyPromise;
+
+    if (!this.account) {
+      this.tryRetrieveSessionAccount();
+    }
 
     if (this.account) {
       return this.account;
@@ -319,7 +328,7 @@ export default class SessionProvider extends BaseProvider {
       };
       localStorage.setItem("session", JSON.stringify(session));
 
-      this.tryRetrieveFromQueryOrStorage();
+      this.tryRetrieveSessionAccount();
 
       return this.account;
     } catch (e) {
@@ -367,15 +376,15 @@ export default class SessionProvider extends BaseProvider {
     return promise;
   }
 
-  tryRetrieveFromQueryOrStorage() {
+  // Try to retrieve the session account from localStorage or URL query params
+  private tryRetrieveSessionAccount() {
     if (this.account) {
       return this.account;
     }
 
-    const signerString = localStorage.getItem("sessionSigner");
-    const signer = signerString ? JSON.parse(signerString) : null;
     let sessionRegistration: SessionRegistration | null = null;
 
+    // Load session from localStorage (saved by ingestSessionFromRedirect or connect)
     const sessionString = localStorage.getItem("session");
     if (sessionString) {
       const parsed = JSON.parse(sessionString) as Partial<SessionRegistration>;
@@ -388,9 +397,9 @@ export default class SessionProvider extends BaseProvider {
       }
     }
 
-    if (window.location.search.includes("startapp")) {
+    if (window.location.search.includes(REDIRECT_QUERY_NAME)) {
       const params = new URLSearchParams(window.location.search);
-      const session = params.get("startapp");
+      const session = params.get(REDIRECT_QUERY_NAME);
       if (session) {
         const normalizedSession = this.ingestSessionFromRedirect(session);
         if (
@@ -402,7 +411,7 @@ export default class SessionProvider extends BaseProvider {
         }
 
         // Remove the session query parameter
-        params.delete("startapp");
+        params.delete(REDIRECT_QUERY_NAME);
         const newUrl =
           window.location.pathname +
           (params.toString() ? `?${params.toString()}` : "") +
@@ -411,6 +420,9 @@ export default class SessionProvider extends BaseProvider {
       }
     }
 
+    const signerString = localStorage.getItem("sessionSigner");
+    const signer = signerString ? JSON.parse(signerString) : null;
+
     if (!sessionRegistration || !signer) {
       return;
     }

package/.turbo/turbo-build.log

@@ -1,79 +0,0 @@
-
-> @cartridge/controller@0.13.7 build /home/runner/work/controller/controller/packages/controller
-> pnpm build:browser && pnpm build:node
-
-
-> @cartridge/controller@0.13.7 build:browser /home/runner/work/controller/controller/packages/controller
-> vite build
-
-vite v6.3.4 building for production...
-src/lookup.ts:116:7 - error TS2322: Type 'string[]' is not assignable to type '("base" | "metamask" | "rabby" | "phantom-evm" | "argent" | "braavos" | "phantom" | "google" | "webauthn" | "discord" | "walletconnect" | "password")[]'.
-  Type 'string' is not assignable to type '"base" | "metamask" | "rabby" | "phantom-evm" | "argent" | "braavos" | "phantom" | "google" | "webauthn" | "discord" | "walletconnect" | "password"'.
-
-116 const HEADLESS_AUTH_OPTIONS: AuthOption[] = [
-          ~~~~~~~~~~~~~~~~~~~~~
-src/lookup.ts:125:56 - error TS2345: Argument of type 'string' is not assignable to parameter of type '"metamask" | "rabby" | "phantom-evm" | "google" | "webauthn" | "discord" | "walletconnect" | "password"'.
-
-125 ].filter((option) => IMPLEMENTED_AUTH_OPTIONS.includes(option));
-                                                           ~~~~~~
-
-transforming...
-../../node_modules/.pnpm/ox@0.4.4_typescript@5.8.3_zod@3.24.4/node_modules/ox/_esm/core/Address.js (6:21): A comment
-
-"/*#__PURE__*/"
-
-in "../../node_modules/.pnpm/ox@0.4.4_typescript@5.8.3_zod@3.24.4/node_modules/ox/_esm/core/Address.js" contains an annotation that Rollup cannot interpret due to the position of the comment. The comment will be removed to avoid issues.
-../../node_modules/.pnpm/ox@0.4.4_typescript@5.8.3_zod@3.24.4/node_modules/ox/_esm/core/Base64.js (6:27): A comment
-
-"/*#__PURE__*/"
-
-in "../../node_modules/.pnpm/ox@0.4.4_typescript@5.8.3_zod@3.24.4/node_modules/ox/_esm/core/Base64.js" contains an annotation that Rollup cannot interpret due to the position of the comment. The comment will be removed to avoid issues.
-../../node_modules/.pnpm/ox@0.4.4_typescript@5.8.3_zod@3.24.4/node_modules/ox/_esm/core/Json.js (1:21): A comment
-
-"/*#__PURE__*/"
-
-in "../../node_modules/.pnpm/ox@0.4.4_typescript@5.8.3_zod@3.24.4/node_modules/ox/_esm/core/Json.js" contains an annotation that Rollup cannot interpret due to the position of the comment. The comment will be removed to avoid issues.
-../../node_modules/.pnpm/ox@0.4.4_typescript@5.8.3_zod@3.24.4/node_modules/ox/_esm/core/internal/cursor.js (2:21): A comment
-
-"/*#__PURE__*/"
-
-in "../../node_modules/.pnpm/ox@0.4.4_typescript@5.8.3_zod@3.24.4/node_modules/ox/_esm/core/internal/cursor.js" contains an annotation that Rollup cannot interpret due to the position of the comment. The comment will be removed to avoid issues.
-✓ 389 modules transformed.
-rendering chunks...
-[plugin vite:reporter] 
-(!) /home/runner/work/controller/controller/packages/controller/src/toast/index.ts is dynamically imported by /home/runner/work/controller/controller/packages/controller/src/account.ts but also statically imported by /home/runner/work/controller/controller/packages/controller/src/index.ts, dynamic import will not move module into another chunk.
-
-
-[vite:dts] Start generate declaration files...
-computing gzip size...
-dist/session.js          10.53 kB │ gzip:  3.24 kB │ map:  25.46 kB
-dist/index-CYAUAqql.js   38.34 kB │ gzip: 12.80 kB │ map:  81.12 kB
-dist/index.js           188.96 kB │ gzip: 49.77 kB │ map: 576.04 kB
-[vite:dts] Declaration files built in 3619ms.
-
-✓ built in 5.80s
-
-> @cartridge/controller@0.13.7 build:node /home/runner/work/controller/controller/packages/controller
-> tsup --config tsup.node.config.ts
-
-CLI Building entry: src/node/index.ts
-CLI Using tsconfig: tsconfig.json
-CLI tsup v8.4.0
-CLI Using tsup config: /home/runner/work/controller/controller/packages/controller/tsup.node.config.ts
-CLI Target: esnext
-CLI Cleaning output folder
-ESM Build start
-CJS Build start
-"constants" and "shortString" are imported from external module "starknet" but never used in "dist/node/index.js".
-"constants" and "shortString" are imported from external module "starknet" but never used in "dist/node/index.cjs".
-Entry module "dist/node/index.cjs" is using named and default exports together. Consumers of your bundle will have to use `chunk.default` to access the default export, which may not be what you want. Use `output.exports: "named"` to disable this warning.
-ESM dist/node/index.js     23.50 KB
-ESM dist/node/index.js.map 56.57 KB
-ESM ⚡️ Build success in 289ms
-CJS dist/node/index.cjs     24.40 KB
-CJS dist/node/index.cjs.map 56.82 KB
-CJS ⚡️ Build success in 289ms
-DTS Build start
-DTS ⚡️ Build success in 3087ms
-DTS dist/node/index.d.ts  6.42 KB
-DTS dist/node/index.d.cts 6.42 KB