@cartridge/controller 0.13.6 → 0.13.9

package/dist/types.d.ts

@@ -70,6 +70,11 @@ export interface LookupResult {
 export interface LookupResponse {
     results: LookupResult[];
 }
+export interface HeadlessUsernameLookupResult {
+    username: string;
+    exists: boolean;
+    signers: AuthOption[];
+}
 export declare enum FeeSource {
     PAYMASTER = "PAYMASTER",
     CREDITS = "CREDITS"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cartridge/controller",
-  "version": "0.13.6",
+  "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.6"
+    "@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/__tests__/lookupUsername.test.ts

@@ -0,0 +1,166 @@
+import { constants } from "starknet";
+import ControllerProvider from "../controller";
+import { IMPLEMENTED_AUTH_OPTIONS } from "../types";
+
+describe("lookupUsername", () => {
+  beforeEach(() => {
+    (global as any).fetch = jest.fn();
+  });
+
+  afterEach(() => {
+    jest.resetAllMocks();
+  });
+
+  test("returns normalized signer options in canonical order", async () => {
+    (global.fetch as jest.Mock).mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        data: {
+          account: {
+            username: "alice",
+            controllers: {
+              edges: [
+                {
+                  node: {
+                    signers: [
+                      {
+                        isOriginal: true,
+                        isRevoked: false,
+                        metadata: {
+                          __typename: "Eip191Credentials",
+                          eip191: [
+                            { provider: "metamask", ethAddress: "0x1" },
+                            { provider: "google", ethAddress: "0x2" },
+                            { provider: "unknown", ethAddress: "0x3" },
+                          ],
+                        },
+                      },
+                      {
+                        isOriginal: true,
+                        isRevoked: false,
+                        metadata: { __typename: "PasswordCredentials" },
+                      },
+                      {
+                        isOriginal: true,
+                        isRevoked: false,
+                        metadata: { __typename: "WebauthnCredentials" },
+                      },
+                      {
+                        isOriginal: true,
+                        isRevoked: true,
+                        metadata: { __typename: "WebauthnCredentials" },
+                      },
+                      {
+                        isOriginal: true,
+                        isRevoked: false,
+                        metadata: {
+                          __typename: "Eip191Credentials",
+                          eip191: [{ provider: "discord", ethAddress: "0x4" }],
+                        },
+                      },
+                    ],
+                  },
+                },
+              ],
+            },
+          },
+        },
+      }),
+    });
+
+    const provider = new ControllerProvider({ lazyload: true });
+    const result = await provider.lookupUsername("alice");
+    const expectedOrder = IMPLEMENTED_AUTH_OPTIONS.filter((option) =>
+      ["google", "webauthn", "discord", "password", "metamask"].includes(
+        option,
+      ),
+    );
+
+    expect(result).toEqual({
+      username: "alice",
+      exists: true,
+      signers: expectedOrder,
+    });
+    expect(global.fetch).toHaveBeenCalledWith(
+      "https://api.cartridge.gg/query",
+      expect.any(Object),
+    );
+  });
+
+  test("filters non-original signers on non-mainnet chains", async () => {
+    (global.fetch as jest.Mock).mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        data: {
+          account: {
+            username: "alice",
+            controllers: {
+              edges: [
+                {
+                  node: {
+                    signers: [
+                      {
+                        isOriginal: false,
+                        isRevoked: false,
+                        metadata: {
+                          __typename: "Eip191Credentials",
+                          eip191: [{ provider: "google", ethAddress: "0x1" }],
+                        },
+                      },
+                      {
+                        isOriginal: true,
+                        isRevoked: false,
+                        metadata: { __typename: "PasswordCredentials" },
+                      },
+                    ],
+                  },
+                },
+              ],
+            },
+          },
+        },
+      }),
+    });
+
+    const provider = new ControllerProvider({
+      lazyload: true,
+      defaultChainId: constants.StarknetChainId.SN_SEPOLIA,
+    });
+    const result = await provider.lookupUsername("alice");
+
+    expect(result.signers).toEqual(["password"]);
+  });
+
+  test("returns exists=false for unknown usernames", async () => {
+    (global.fetch as jest.Mock).mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        data: {
+          account: null,
+        },
+      }),
+    });
+
+    const provider = new ControllerProvider({ lazyload: true });
+    const result = await provider.lookupUsername("missing-user");
+
+    expect(result).toEqual({
+      username: "missing-user",
+      exists: false,
+      signers: [],
+    });
+  });
+
+  test("throws on network failures", async () => {
+    (global.fetch as jest.Mock).mockResolvedValue({
+      ok: false,
+      status: 503,
+    });
+
+    const provider = new ControllerProvider({ lazyload: true });
+
+    await expect(provider.lookupUsername("alice")).rejects.toThrow(
+      "HTTP error! status: 503",
+    );
+  });
+});

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

@@ -15,6 +15,7 @@ import { KEYCHAIN_URL } from "./constants";
 import { HeadlessAuthenticationError, NotReadyToConnect } from "./errors";
 import { KeychainIFrame } from "./iframe";
 import BaseProvider from "./provider";
+import { lookupUsername as lookupUsernameApi } from "./lookup";
 import {
   AuthOptions,
   Chain,
@@ -28,6 +29,7 @@ import {
   ProfileContextTypeVariant,
   ResponseCodes,
   OpenOptions,
+  HeadlessUsernameLookupResult,
   StarterpackOptions,
 } from "./types";
 import { validateRedirectUrl } from "./url-validator";
@@ -393,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.
@@ -530,6 +539,17 @@ export default class ControllerProvider extends BaseProvider {
     return this.keychain.username();
   }
 
+  async lookupUsername(
+    username: string,
+  ): Promise<HeadlessUsernameLookupResult> {
+    const trimmed = username.trim();
+    if (!trimmed) {
+      throw new Error("Username is required");
+    }
+
+    return lookupUsernameApi(trimmed, this.selectedChain);
+  }
+
   openPurchaseCredits() {
     if (!this.iframes) {
       return;

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/lookup.ts

@@ -1,8 +1,43 @@
-import { LookupRequest, LookupResponse } from "./types";
-import { num } from "starknet";
+import {
+  AuthOption,
+  HeadlessUsernameLookupResult,
+  IMPLEMENTED_AUTH_OPTIONS,
+  LookupRequest,
+  LookupResponse,
+} from "./types";
+import { constants, num } from "starknet";
 import { API_URL } from "./constants";
 
 const cache = new Map<string, string>();
+const QUERY_URL = `${API_URL}/query`;
+
+type LookupSigner = {
+  isOriginal: boolean;
+  isRevoked: boolean;
+  metadata: {
+    __typename: string;
+    eip191?: Array<{
+      provider: string;
+      ethAddress: string;
+    }> | null;
+  };
+};
+
+type LookupSignersQueryResponse = {
+  data?: {
+    account?: {
+      username: string;
+      controllers?: {
+        edges?: Array<{
+          node?: {
+            signers?: LookupSigner[] | null;
+          } | null;
+        } | null> | null;
+      } | null;
+    } | null;
+  };
+  errors?: Array<{ message?: string }>;
+};
 
 async function lookup(request: LookupRequest): Promise<LookupResponse> {
   if (!request.addresses?.length && !request.usernames?.length) {
@@ -24,6 +59,139 @@ async function lookup(request: LookupRequest): Promise<LookupResponse> {
   return response.json();
 }
 
+async function queryLookupSigners(
+  username: string,
+): Promise<LookupSignersQueryResponse> {
+  const response = await fetch(QUERY_URL, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      query: `
+        query LookupSigners($username: String!) {
+          account(username: $username) {
+            username
+            controllers(first: 1) {
+              edges {
+                node {
+                  signers {
+                    isOriginal
+                    isRevoked
+                    metadata {
+                      __typename
+                      ... on Eip191Credentials {
+                        eip191 {
+                          provider
+                          ethAddress
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      `,
+      variables: { username },
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`HTTP error! status: ${response.status}`);
+  }
+
+  return response.json();
+}
+
+function normalizeProvider(provider: string): AuthOption | undefined {
+  const normalized = provider.toLowerCase() as AuthOption;
+  if (!HEADLESS_AUTH_OPTIONS.includes(normalized)) {
+    return undefined;
+  }
+  return normalized;
+}
+
+const HEADLESS_AUTH_OPTIONS: AuthOption[] = [
+  "google",
+  "webauthn",
+  "discord",
+  "walletconnect",
+  "password",
+  "metamask",
+  "rabby",
+  "phantom-evm",
+].filter((option) => IMPLEMENTED_AUTH_OPTIONS.includes(option));
+
+function normalizeSignerOptions(
+  signers: LookupSigner[] | undefined,
+  chainId: string,
+): AuthOption[] {
+  if (!signers || signers.length === 0) {
+    return [];
+  }
+
+  const isMainnet = chainId === constants.StarknetChainId.SN_MAIN;
+  const available = signers.filter(
+    (signer) => !signer.isRevoked && (isMainnet || signer.isOriginal),
+  );
+
+  const signerSet = new Set<AuthOption>();
+  for (const signer of available) {
+    switch (signer.metadata.__typename) {
+      case "WebauthnCredentials":
+        signerSet.add("webauthn");
+        break;
+      case "PasswordCredentials":
+        signerSet.add("password");
+        break;
+      case "Eip191Credentials":
+        signer.metadata.eip191?.forEach((entry) => {
+          const provider = normalizeProvider(entry.provider);
+          if (provider) {
+            signerSet.add(provider);
+          }
+        });
+        break;
+      default:
+        break;
+    }
+  }
+
+  return HEADLESS_AUTH_OPTIONS.filter((option) => signerSet.has(option));
+}
+
+export async function lookupUsername(
+  username: string,
+  chainId: string,
+): Promise<HeadlessUsernameLookupResult> {
+  const response = await queryLookupSigners(username);
+  if (response.errors?.length) {
+    throw new Error(response.errors[0].message || "Lookup query failed");
+  }
+
+  const account = response.data?.account;
+  if (!account) {
+    return {
+      username,
+      exists: false,
+      signers: [],
+    };
+  }
+
+  const controller = account.controllers?.edges?.[0]?.node;
+  const signers = normalizeSignerOptions(
+    controller?.signers ?? undefined,
+    chainId,
+  );
+  return {
+    username: account.username,
+    exists: true,
+    signers,
+  };
+}
+
 export async function lookupUsernames(
   usernames: string[],
 ): Promise<Map<string, string>> {

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");