@cartridge/controller 0.13.5 → 0.13.6

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.6",
   "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.6"
   },
   "scripts": {
     "build:deps": "pnpm build",

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/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

package/src/session/provider.ts

@@ -4,14 +4,14 @@ import {
   signerToGuid,
   subscribeCreateSession,
 } from "@cartridge/controller-wasm";
-import { SessionPolicies } from "@cartridge/presets";
+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 { ParsedSessionPolicies } from "../policies";
+import { parsePolicies, ParsedSessionPolicies } from "../policies";
 import BaseProvider from "../provider";
 import { AuthOptions } from "../types";
-import { toWasmPolicies } from "../utils";
+import { getPresetSessionPolicies, toWasmPolicies } from "../utils";
 import SessionAccount from "./account";
 
 interface SessionRegistration {
@@ -29,7 +29,9 @@ interface SessionRegistration {
 export type SessionOptions = {
   rpc: string;
   chainId: string;
-  policies: SessionPolicies;
+  policies?: SessionPolicies;
+  preset?: string;
+  shouldOverridePresetPolicies?: boolean;
   redirectUrl: string;
   disconnectRedirectUrl?: string;
   keychainUrl?: string;
@@ -47,10 +49,12 @@ export default class SessionProvider extends BaseProvider {
   protected _redirectUrl: string;
   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 _publicKey!: string;
+  protected _sessionKeyGuid!: string;
   protected _signupOptions?: AuthOptions;
   public reopenBrowser: boolean = true;
 
@@ -58,6 +62,8 @@ export default class SessionProvider extends BaseProvider {
     rpc,
     chainId,
     policies,
+    preset,
+    shouldOverridePresetPolicies,
     redirectUrl,
     disconnectRedirectUrl,
     keychainUrl,
@@ -66,27 +72,27 @@ export default class SessionProvider extends BaseProvider {
   }: SessionOptions) {
     super();
 
-    this._policies = {
-      verified: false,
-      contracts: policies.contracts
-        ? Object.fromEntries(
-            Object.entries(policies.contracts).map(([address, contract]) => [
-              address,
-              {
-                ...contract,
-                methods: contract.methods.map((method) => ({
-                  ...method,
-                  authorized: true,
-                })),
-              },
-            ]),
-          )
-        : undefined,
-      messages: policies.messages?.map((message) => ({
-        ...message,
-        authorized: true,
-      })),
-    };
+    if (!policies && !preset) {
+      throw new Error("Either `policies` or `preset` must be provided");
+    }
+
+    // Policy precedence logic (matching ControllerProvider):
+    // 1. If shouldOverridePresetPolicies is true and policies are provided, use policies
+    // 2. Otherwise, if preset is defined, resolve policies from preset
+    // 3. Otherwise, use provided policies
+    if ((!preset || shouldOverridePresetPolicies) && policies) {
+      this._policies = parsePolicies(policies);
+    } else {
+      this._preset = preset;
+      if (policies) {
+        console.warn(
+          "[Controller] Both `preset` and `policies` provided to SessionProvider. " +
+            "Policies are ignored when preset is set. " +
+            "Use `shouldOverridePresetPolicies: true` to override.",
+        );
+      }
+      this._policies = { verified: false };
+    }
 
     this._rpcUrl = rpc;
     this._chainId = chainId;
@@ -96,6 +102,33 @@ 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();
+
+    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) {
       const pk = stark.randomAddress();
@@ -125,10 +158,6 @@ export default class SessionProvider extends BaseProvider {
         starknet: { privateKey: encode.addHexPrefix(jsonPk.privKey) },
       });
     }
-
-    if (typeof window !== "undefined") {
-      (window as any).starknet_controller_session = this;
-    }
   }
 
   private validatePoliciesSubset(
@@ -218,25 +247,18 @@ export default class SessionProvider extends BaseProvider {
   }
 
   async username() {
-    await this.tryRetrieveFromQueryOrStorage();
+    await this._ready;
     return this._username;
   }
 
   async probe(): Promise<WalletAccount | undefined> {
-    if (this.account) {
-      return this.account;
-    }
-
-    this.account = this.tryRetrieveFromQueryOrStorage();
+    await this._ready;
     return this.account;
   }
 
   async connect(): Promise<WalletAccount | undefined> {
-    if (this.account) {
-      return this.account;
-    }
+    await this._ready;
 
-    this.account = this.tryRetrieveFromQueryOrStorage();
     if (this.account) {
       return this.account;
     }
@@ -259,13 +281,18 @@ export default class SessionProvider extends BaseProvider {
         this._sessionKeyGuid = signerToGuid({
           starknet: { privateKey: encode.addHexPrefix(pk) },
         });
-        let url = `${
-          this._keychainUrl
-        }/session?public_key=${this._publicKey}&redirect_uri=${
-          this._redirectUrl
-        }&redirect_query_name=startapp&policies=${JSON.stringify(
-          this._policies,
-        )}&rpc_url=${this._rpcUrl}`;
+        let url =
+          `${this._keychainUrl}` +
+          `/session?public_key=${this._publicKey}` +
+          `&redirect_uri=${this._redirectUrl}` +
+          `&redirect_query_name=startapp` +
+          `&rpc_url=${this._rpcUrl}`;
+
+        if (this._preset) {
+          url += `&preset=${encodeURIComponent(this._preset)}`;
+        } else {
+          url += `&policies=${encodeURIComponent(JSON.stringify(this._policies))}`;
+        }
 
         if (this._signupOptions) {
           url += `&signers=${encodeURIComponent(JSON.stringify(this._signupOptions))}`;

package/src/utils.ts

@@ -48,6 +48,19 @@ export function normalizeCalls(calls: Call | Call[]) {
   });
 }
 
+export function getPresetSessionPolicies(
+  config: Record<string, unknown>,
+  chainId: string,
+): SessionPolicies | undefined {
+  const decodedChainId = shortString.decodeShortString(chainId);
+  const chains = config.chains as
+    | Record<string, Record<string, unknown>>
+    | undefined;
+  const chainConfig = chains?.[decodedChainId];
+  if (!chainConfig?.policies) return undefined;
+  return toSessionPolicies(chainConfig.policies as Policies);
+}
+
 export function toSessionPolicies(policies: Policies): SessionPolicies {
   return Array.isArray(policies)
     ? policies.reduce<SessionPolicies>(
@@ -92,9 +105,10 @@ export 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 function toWasmPolicies(policies: ParsedSessionPolicies): Policy[] {
@@ -110,7 +124,7 @@ export function toWasmPolicies(policies: ParsedSessionPolicies): Policy[] {
             if (m.entrypoint === "approve") {
               if ("spender" in m && "amount" in m && m.spender && m.amount) {
                 const approvalPolicy: ApprovalPolicy = {
-                  target,
+                  target: getChecksumAddress(target),
                   spender: m.spender,
                   amount: String(m.amount),
                 };
@@ -127,7 +141,7 @@ export function toWasmPolicies(policies: ParsedSessionPolicies): Policy[] {
 
             // For non-approve methods and legacy approve, create a regular CallPolicy
             return {
-              target,
+              target: getChecksumAddress(target),
               method: hash.getSelectorFromName(m.entrypoint),
               authorized: !!m.authorized,
             };