@cartridge/controller 0.13.5 → 0.13.7

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/dist/utils.d.ts

@@ -8,13 +8,15 @@ export declare function normalizeCalls(calls: Call | Call[]): {
     contractAddress: string;
     calldata: import('starknet').HexCalldata;
 }[];
+export declare function getPresetSessionPolicies(config: Record<string, unknown>, chainId: string): SessionPolicies | undefined;
 export declare function toSessionPolicies(policies: Policies): SessionPolicies;
 /**
  * Converts parsed session policies to WASM-compatible Policy objects.
  *
- * IMPORTANT: Policies are sorted canonically before hashing. Without this,
- * Object.keys/entries reordering can cause identical policies to produce
- * different merkle roots, leading to "session/not-registered" errors.
+ * IMPORTANT: Policies are sorted canonically and addresses are normalized
+ * via getChecksumAddress before hashing. Without this, Object.keys/entries
+ * reordering or inconsistent address casing can cause identical policies to
+ * produce different merkle roots, leading to "session/not-registered" errors.
  * See: https://github.com/cartridge-gg/controller/issues/2357
  */
 export declare function toWasmPolicies(policies: ParsedSessionPolicies): Policy[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cartridge/controller",
-  "version": "0.13.5",
+  "version": "0.13.7",
   "description": "Cartridge Controller",
   "repository": {
     "type": "git",
@@ -56,7 +56,7 @@
     "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.5"
+    "@cartridge/tsconfig": "0.13.7"
   },
   "scripts": {
     "build:deps": "pnpm build",

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/__tests__/toWasmPolicies.test.ts

@@ -1,16 +1,27 @@
+import { getChecksumAddress } from "starknet";
 import { toWasmPolicies } from "../utils";
 import { ParsedSessionPolicies } from "../policies";
 
+// Valid hex addresses for testing (short but valid for getChecksumAddress)
+const ADDR_A = "0x0aaa";
+const ADDR_B = "0x0bbb";
+const ADDR_C = "0x0ccc";
+
+// Pre-compute checksummed forms
+const ADDR_A_CS = getChecksumAddress(ADDR_A);
+const ADDR_B_CS = getChecksumAddress(ADDR_B);
+const ADDR_C_CS = getChecksumAddress(ADDR_C);
+
 describe("toWasmPolicies", () => {
   describe("canonical ordering", () => {
     test("sorts contracts by address regardless of input order", () => {
       const policies1: ParsedSessionPolicies = {
         verified: false,
         contracts: {
-          "0xAAA": {
+          [ADDR_A]: {
             methods: [{ entrypoint: "foo", authorized: true }],
           },
-          "0xBBB": {
+          [ADDR_B]: {
             methods: [{ entrypoint: "bar", authorized: true }],
           },
         },
@@ -19,10 +30,10 @@ describe("toWasmPolicies", () => {
       const policies2: ParsedSessionPolicies = {
         verified: false,
         contracts: {
-          "0xBBB": {
+          [ADDR_B]: {
             methods: [{ entrypoint: "bar", authorized: true }],
           },
-          "0xAAA": {
+          [ADDR_A]: {
             methods: [{ entrypoint: "foo", authorized: true }],
           },
         },
@@ -32,16 +43,16 @@ describe("toWasmPolicies", () => {
       const result2 = toWasmPolicies(policies2);
 
       expect(result1).toEqual(result2);
-      // First policy should be for 0xAAA (sorted alphabetically)
-      expect(result1[0]).toHaveProperty("target", "0xAAA");
-      expect(result1[1]).toHaveProperty("target", "0xBBB");
+      // First policy should be for ADDR_A (sorted alphabetically)
+      expect(result1[0]).toHaveProperty("target", ADDR_A_CS);
+      expect(result1[1]).toHaveProperty("target", ADDR_B_CS);
     });
 
     test("sorts methods within contracts by entrypoint", () => {
       const policies1: ParsedSessionPolicies = {
         verified: false,
         contracts: {
-          "0xAAA": {
+          [ADDR_A]: {
             methods: [
               { entrypoint: "zebra", authorized: true },
               { entrypoint: "apple", authorized: true },
@@ -54,7 +65,7 @@ describe("toWasmPolicies", () => {
       const policies2: ParsedSessionPolicies = {
         verified: false,
         contracts: {
-          "0xAAA": {
+          [ADDR_A]: {
             methods: [
               { entrypoint: "mango", authorized: true },
               { entrypoint: "zebra", authorized: true },
@@ -74,19 +85,19 @@ describe("toWasmPolicies", () => {
       const policies1: ParsedSessionPolicies = {
         verified: false,
         contracts: {
-          "0xCCC": {
+          [ADDR_C]: {
             methods: [
               { entrypoint: "c_method", authorized: true },
               { entrypoint: "a_method", authorized: true },
             ],
           },
-          "0xAAA": {
+          [ADDR_A]: {
             methods: [
               { entrypoint: "z_method", authorized: true },
               { entrypoint: "a_method", authorized: true },
             ],
           },
-          "0xBBB": {
+          [ADDR_B]: {
             methods: [{ entrypoint: "b_method", authorized: true }],
           },
         },
@@ -96,16 +107,16 @@ describe("toWasmPolicies", () => {
       const policies2: ParsedSessionPolicies = {
         verified: false,
         contracts: {
-          "0xBBB": {
+          [ADDR_B]: {
             methods: [{ entrypoint: "b_method", authorized: true }],
           },
-          "0xAAA": {
+          [ADDR_A]: {
             methods: [
               { entrypoint: "a_method", authorized: true },
               { entrypoint: "z_method", authorized: true },
             ],
           },
-          "0xCCC": {
+          [ADDR_C]: {
             methods: [
               { entrypoint: "a_method", authorized: true },
               { entrypoint: "c_method", authorized: true },
@@ -119,21 +130,21 @@ describe("toWasmPolicies", () => {
 
       expect(result1).toEqual(result2);
 
-      // Verify order: 0xAAA first, then 0xBBB, then 0xCCC
-      // Within 0xAAA: a_method before z_method
-      expect(result1[0]).toHaveProperty("target", "0xAAA");
-      expect(result1[2]).toHaveProperty("target", "0xBBB");
-      expect(result1[3]).toHaveProperty("target", "0xCCC");
+      // Verify order: ADDR_A first, then ADDR_B, then ADDR_C
+      // Within ADDR_A: a_method before z_method
+      expect(result1[0]).toHaveProperty("target", ADDR_A_CS);
+      expect(result1[2]).toHaveProperty("target", ADDR_B_CS);
+      expect(result1[3]).toHaveProperty("target", ADDR_C_CS);
     });
 
     test("handles case-insensitive address sorting", () => {
       const policies1: ParsedSessionPolicies = {
         verified: false,
         contracts: {
-          "0xaaa": {
+          "0x0aaa": {
             methods: [{ entrypoint: "foo", authorized: true }],
           },
-          "0xAAB": {
+          "0x0AAB": {
             methods: [{ entrypoint: "bar", authorized: true }],
           },
         },
@@ -142,10 +153,10 @@ describe("toWasmPolicies", () => {
       const policies2: ParsedSessionPolicies = {
         verified: false,
         contracts: {
-          "0xAAB": {
+          "0x0AAB": {
             methods: [{ entrypoint: "bar", authorized: true }],
           },
-          "0xaaa": {
+          "0x0aaa": {
             methods: [{ entrypoint: "foo", authorized: true }],
           },
         },
@@ -157,6 +168,34 @@ describe("toWasmPolicies", () => {
       expect(result1).toEqual(result2);
     });
 
+    test("normalizes address casing via getChecksumAddress", () => {
+      const addr =
+        "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7";
+      const policies1: ParsedSessionPolicies = {
+        verified: false,
+        contracts: {
+          [addr.toLowerCase()]: {
+            methods: [{ entrypoint: "transfer", authorized: true }],
+          },
+        },
+      };
+
+      const policies2: ParsedSessionPolicies = {
+        verified: false,
+        contracts: {
+          [addr.toUpperCase().replace("0X", "0x")]: {
+            methods: [{ entrypoint: "transfer", authorized: true }],
+          },
+        },
+      };
+
+      const result1 = toWasmPolicies(policies1);
+      const result2 = toWasmPolicies(policies2);
+
+      expect(result1).toEqual(result2);
+      expect(result1[0]).toHaveProperty("target", getChecksumAddress(addr));
+    });
+
     test("handles empty policies", () => {
       const policies: ParsedSessionPolicies = {
         verified: false,
@@ -179,15 +218,21 @@ describe("toWasmPolicies", () => {
   });
 
   describe("ApprovalPolicy handling", () => {
+    const TOKEN =
+      "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7";
+    const TOKEN_CS = getChecksumAddress(TOKEN);
+    const SPENDER =
+      "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d";
+
     test("creates ApprovalPolicy for approve methods with spender and amount", () => {
       const policies: ParsedSessionPolicies = {
         verified: false,
         contracts: {
-          "0xTOKEN": {
+          [TOKEN]: {
             methods: [
               {
                 entrypoint: "approve",
-                spender: "0xSPENDER",
+                spender: SPENDER,
                 amount: "1000000000000000000",
                 authorized: true,
               },
@@ -200,8 +245,8 @@ describe("toWasmPolicies", () => {
 
       expect(result).toHaveLength(1);
       expect(result[0]).toEqual({
-        target: "0xTOKEN",
-        spender: "0xSPENDER",
+        target: TOKEN_CS,
+        spender: SPENDER,
         amount: "1000000000000000000",
       });
       // Should NOT have method or authorized fields
@@ -213,11 +258,11 @@ describe("toWasmPolicies", () => {
       const policies: ParsedSessionPolicies = {
         verified: false,
         contracts: {
-          "0xTOKEN": {
+          [TOKEN]: {
             methods: [
               {
                 entrypoint: "approve",
-                spender: "0xSPENDER",
+                spender: SPENDER,
                 amount: 1000000000000000000,
                 authorized: true,
               },
@@ -237,7 +282,7 @@ describe("toWasmPolicies", () => {
       const policies: ParsedSessionPolicies = {
         verified: false,
         contracts: {
-          "0xTOKEN": {
+          [TOKEN]: {
             methods: [
               {
                 entrypoint: "approve",
@@ -267,11 +312,11 @@ describe("toWasmPolicies", () => {
       const policies: ParsedSessionPolicies = {
         verified: false,
         contracts: {
-          "0xTOKEN": {
+          [TOKEN]: {
             methods: [
               {
                 entrypoint: "approve",
-                spender: "0xSPENDER",
+                spender: SPENDER,
                 authorized: true,
               },
             ],
@@ -290,10 +335,14 @@ describe("toWasmPolicies", () => {
     });
 
     test("creates CallPolicy for non-approve methods", () => {
+      const CONTRACT =
+        "0x0124aeb495b947201f5fac96fd1138e326ad86195b98df6dec9009158a533b49";
+      const CONTRACT_CS = getChecksumAddress(CONTRACT);
+
       const policies: ParsedSessionPolicies = {
         verified: false,
         contracts: {
-          "0xCONTRACT": {
+          [CONTRACT]: {
             methods: [
               {
                 entrypoint: "transfer",
@@ -307,7 +356,7 @@ describe("toWasmPolicies", () => {
       const result = toWasmPolicies(policies);
 
       expect(result).toHaveLength(1);
-      expect(result[0]).toHaveProperty("target", "0xCONTRACT");
+      expect(result[0]).toHaveProperty("target", CONTRACT_CS);
       expect(result[0]).toHaveProperty("method");
       expect(result[0]).toHaveProperty("authorized", true);
     });
@@ -316,11 +365,11 @@ describe("toWasmPolicies", () => {
       const policies: ParsedSessionPolicies = {
         verified: false,
         contracts: {
-          "0xTOKEN": {
+          [TOKEN]: {
             methods: [
               {
                 entrypoint: "approve",
-                spender: "0xSPENDER",
+                spender: SPENDER,
                 amount: "1000",
                 authorized: true,
               },
@@ -339,7 +388,7 @@ describe("toWasmPolicies", () => {
 
       // First should be approve (sorted alphabetically)
       const approvePolicy = result[0];
-      expect(approvePolicy).toHaveProperty("spender", "0xSPENDER");
+      expect(approvePolicy).toHaveProperty("spender", SPENDER);
       expect(approvePolicy).toHaveProperty("amount", "1000");
 
       // Second should be transfer
@@ -352,12 +401,12 @@ describe("toWasmPolicies", () => {
       const policies: ParsedSessionPolicies = {
         verified: false,
         contracts: {
-          "0xTOKEN": {
+          [TOKEN]: {
             methods: [
               { entrypoint: "transfer", authorized: true },
               {
                 entrypoint: "approve",
-                spender: "0xSPENDER",
+                spender: SPENDER,
                 amount: "1000",
                 authorized: true,
               },

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";
@@ -530,6 +532,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

@@ -104,6 +104,13 @@ export class KeychainIFrame extends IFrame<Keychain> {
       );
     } else if (preset) {
       _url.searchParams.set("preset", preset);
+      if (policies) {
+        console.warn(
+          "[Controller] Both `preset` and `policies` provided to ControllerProvider. " +
+            "Policies are ignored when preset is set. " +
+            "Use `shouldOverridePresetPolicies: true` to override.",
+        );
+      }
     }
 
     // Add encrypted blob to URL fragment (hash) if present