@cartridge/controller 0.13.4 → 0.13.6

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]);
+        }
       },
     });
 

package/src/errors.ts

@@ -5,3 +5,33 @@ export class NotReadyToConnect extends Error {
     Object.setPrototypeOf(this, NotReadyToConnect.prototype);
   }
 }
+
+export class HeadlessAuthenticationError extends Error {
+  constructor(
+    message: string,
+    public cause?: Error,
+  ) {
+    super(message);
+    this.name = "HeadlessAuthenticationError";
+
+    Object.setPrototypeOf(this, HeadlessAuthenticationError.prototype);
+  }
+}
+
+export class InvalidCredentialsError extends HeadlessAuthenticationError {
+  constructor(credentialType: string) {
+    super(`Invalid credentials provided for type: ${credentialType}`);
+    this.name = "InvalidCredentialsError";
+
+    Object.setPrototypeOf(this, InvalidCredentialsError.prototype);
+  }
+}
+
+export class HeadlessModeNotSupportedError extends Error {
+  constructor(operation: string) {
+    super(`Operation "${operation}" is not supported in headless mode`);
+    this.name = "HeadlessModeNotSupportedError";
+
+    Object.setPrototypeOf(this, HeadlessModeNotSupportedError.prototype);
+  }
+}

package/src/iframe/base.ts

@@ -1,5 +1,6 @@
 import { AsyncMethodReturns, connectToChild } from "@cartridge/penpal";
 import { Modal } from "../types";
+import { buildIframeAllowList, validateKeychainIframeUrl } from "./security";
 
 export type IFrameOptions<CallSender> = Omit<
   ConstructorParameters<typeof IFrame>[0],
@@ -34,6 +35,7 @@ export class IFrame<CallSender extends {}> implements Modal {
     }
 
     this.url = url;
+    validateKeychainIframeUrl(url);
 
     const docHead = document.head;
 
@@ -53,8 +55,8 @@ export class IFrame<CallSender extends {}> implements Modal {
     iframe.sandbox.add("allow-popups-to-escape-sandbox");
     iframe.sandbox.add("allow-scripts");
     iframe.sandbox.add("allow-same-origin");
-    iframe.allow =
-      "publickey-credentials-create *; publickey-credentials-get *; clipboard-write; local-network-access *; payment *";
+    iframe.allow = buildIframeAllowList(url);
+    iframe.referrerPolicy = "no-referrer";
     iframe.style.scrollbarWidth = "none";
     iframe.style.setProperty("-ms-overflow-style", "none");
     iframe.style.setProperty("-webkit-scrollbar", "none");
@@ -122,12 +124,21 @@ export class IFrame<CallSender extends {}> implements Modal {
 
     connectToChild<CallSender>({
       iframe: this.iframe,
+      childOrigin: url.origin,
       methods: {
+        open: (_origin: string) => () => this.open(),
         close: (_origin: string) => () => this.close(),
         reload: (_origin: string) => () => window.location.reload(),
         ...methods,
       },
-    }).promise.then(onConnect);
+    })
+      .promise.then(onConnect)
+      .catch((error) => {
+        console.error("Failed to establish secure keychain iframe connection", {
+          error,
+          childOrigin: url.origin,
+        });
+      });
 
     this.resize();
     window.addEventListener("resize", () => this.resize());

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
@@ -119,11 +126,7 @@ export class KeychainIFrame extends IFrame<Keychain> {
       methods: {
         ...walletBridge.getIFrameMethods(),
         // Expose callback for keychain to notify parent that session was created and storage access granted
-        onSessionCreated: (_origin: string) => () => {
-          if (onSessionCreated) {
-            onSessionCreated();
-          }
-        },
+        onSessionCreated: (_origin: string) => () => onSessionCreated?.(),
         onStarterpackPlay: (_origin: string) => async () => {
           if (onStarterpackPlayHandler) {
             await onStarterpackPlayHandler();

package/src/iframe/security.ts

@@ -0,0 +1,48 @@
+const LOCALHOST_HOSTNAMES = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+
+export function isLocalhostHostname(hostname: string): boolean {
+  const normalized = hostname.toLowerCase();
+  return (
+    LOCALHOST_HOSTNAMES.has(normalized) || normalized.endsWith(".localhost")
+  );
+}
+
+/**
+ * Restrict iframe targets to HTTPS in production, while still allowing local HTTP dev.
+ */
+export function validateKeychainIframeUrl(url: URL): void {
+  if (url.username || url.password) {
+    throw new Error("Invalid keychain iframe URL: credentials are not allowed");
+  }
+
+  if (url.protocol === "https:") {
+    return;
+  }
+
+  if (url.protocol === "http:" && isLocalhostHostname(url.hostname)) {
+    return;
+  }
+
+  throw new Error(
+    "Invalid keychain iframe URL: only https:// or local http:// URLs are allowed",
+  );
+}
+
+/**
+ * Build a conservative allow list for iframe feature policy.
+ * Local network access is only needed for localhost development.
+ */
+export function buildIframeAllowList(url: URL): string {
+  const allowFeatures = [
+    "publickey-credentials-create *",
+    "publickey-credentials-get *",
+    "clipboard-write",
+    "payment *",
+  ];
+
+  if (isLocalhostHostname(url.hostname)) {
+    allowFeatures.push("local-network-access *");
+  }
+
+  return allowFeatures.join("; ");
+}

package/src/index.ts

@@ -3,6 +3,7 @@ export * from "./errors";
 export * from "./types";
 export * from "./lookup";
 export * from "./utils";
+export * from "./policies";
 export * from "./wallets";
 export * from "./toast";
 export * from "@cartridge/presets";

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 {
@@ -23,12 +23,15 @@ interface SessionRegistration {
   guardianKeyGuid: string;
   metadataHash: string;
   sessionKeyGuid: string;
+  allowedPoliciesRoot?: string;
 }
 
 export type SessionOptions = {
   rpc: string;
   chainId: string;
-  policies: SessionPolicies;
+  policies?: SessionPolicies;
+  preset?: string;
+  shouldOverridePresetPolicies?: boolean;
   redirectUrl: string;
   disconnectRedirectUrl?: string;
   keychainUrl?: string;
@@ -46,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;
 
@@ -57,6 +62,8 @@ export default class SessionProvider extends BaseProvider {
     rpc,
     chainId,
     policies,
+    preset,
+    shouldOverridePresetPolicies,
     redirectUrl,
     disconnectRedirectUrl,
     keychainUrl,
@@ -65,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;
@@ -95,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();
@@ -124,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(
@@ -217,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;
     }
@@ -258,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))}`;
@@ -314,6 +342,7 @@ export default class SessionProvider extends BaseProvider {
     localStorage.removeItem("sessionPolicies");
     localStorage.removeItem("lastUsedConnector");
     this.account = undefined;
+    this.emitAccountsChanged([]);
     this._username = undefined;
     const disconnectUrl = new URL(`${this._keychainUrl}`);
     disconnectUrl.pathname = "disconnect";

package/src/types.ts

@@ -131,7 +131,7 @@ 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;
@@ -276,3 +276,32 @@ export type StarterpackOptions = {
   /** Callback fired after the Play button closes the starterpack modal */
   onPurchaseComplete?: () => void;
 };
+
+// Connect options (used by controller.connect)
+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;