@cartridge/controller 0.13.4 → 0.13.6

package/.turbo/turbo-build$colon$deps.log

@@ -1,18 +1,38 @@
 
-> @cartridge/controller@0.13.4 build:deps /home/runner/work/controller/controller/packages/controller
+> @cartridge/controller@0.13.6 build:deps /home/runner/work/controller/controller/packages/controller
 > pnpm build
 
 
-> @cartridge/controller@0.13.4 build /home/runner/work/controller/controller/packages/controller
+> @cartridge/controller@0.13.6 build /home/runner/work/controller/controller/packages/controller
 > pnpm build:browser && pnpm build:node
 
 
-> @cartridge/controller@0.13.4 build:browser /home/runner/work/controller/controller/packages/controller
+> @cartridge/controller@0.13.6 build:browser /home/runner/work/controller/controller/packages/controller
 > vite build
 
 vite v6.3.4 building for production...
 transforming...
-✓ 246 modules transformed.
+../../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.
@@ -20,14 +40,14 @@ rendering chunks...
 
 [vite:dts] Start generate declaration files...
 computing gzip size...
-dist/session.js             10.03 kB │ gzip:  3.01 kB │ map:  23.85 kB
-dist/provider-DSqqvDee.js   15.05 kB │ gzip:  6.17 kB │ map:  39.52 kB
-dist/index.js              196.19 kB │ gzip: 51.71 kB │ map: 547.91 kB
-[vite:dts] Declaration files built in 3525ms.
+dist/session.js          10.53 kB │ gzip:  3.24 kB │ map:  25.46 kB
+dist/index-BdTFKueB.js   38.34 kB │ gzip: 12.80 kB │ map:  81.00 kB
+dist/index.js           186.49 kB │ gzip: 49.14 kB │ map: 569.43 kB
+[vite:dts] Declaration files built in 3707ms.
 
-✓ built in 5.12s
+✓ built in 5.77s
 
-> @cartridge/controller@0.13.4 build:node /home/runner/work/controller/controller/packages/controller
+> @cartridge/controller@0.13.6 build:node /home/runner/work/controller/controller/packages/controller
 > tsup --config tsup.node.config.ts
 
 CLI Building entry: src/node/index.ts
@@ -38,16 +58,16 @@ computing gzip size...
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-"constants", "getChecksumAddress" and "shortString" are imported from external module "starknet" but never used in "dist/node/index.js".
-"constants", "getChecksumAddress" and "shortString" are imported from external module "starknet" but never used in "dist/node/index.cjs".
+"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     22.43 KB
-ESM dist/node/index.js.map 54.20 KB
-ESM ⚡️ Build success in 324ms
-CJS dist/node/index.cjs     23.22 KB
-CJS dist/node/index.cjs.map 54.43 KB
-CJS ⚡️ Build success in 325ms
+ESM dist/node/index.js     23.50 KB
+ESM dist/node/index.js.map 56.57 KB
+ESM ⚡️ Build success in 359ms
+CJS dist/node/index.cjs     24.40 KB
+CJS dist/node/index.cjs.map 56.82 KB
+CJS ⚡️ Build success in 357ms
 DTS Build start
-DTS ⚡️ Build success in 2937ms
-DTS dist/node/index.d.ts  5.98 KB
-DTS dist/node/index.d.cts 5.98 KB
+DTS ⚡️ Build success in 3125ms
+DTS dist/node/index.d.ts  6.42 KB
+DTS dist/node/index.d.cts 6.42 KB

package/.turbo/turbo-build.log

@@ -1,14 +1,34 @@
 
-> @cartridge/controller@0.13.4 build /home/runner/work/controller/controller/packages/controller
+> @cartridge/controller@0.13.6 build /home/runner/work/controller/controller/packages/controller
 > pnpm build:browser && pnpm build:node
 
 
-> @cartridge/controller@0.13.4 build:browser /home/runner/work/controller/controller/packages/controller
+> @cartridge/controller@0.13.6 build:browser /home/runner/work/controller/controller/packages/controller
 > vite build
 
 vite v6.3.4 building for production...
 transforming...
-✓ 246 modules transformed.
+../../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.
@@ -16,14 +36,14 @@ rendering chunks...
 
 [vite:dts] Start generate declaration files...
 computing gzip size...
-dist/session.js             10.03 kB │ gzip:  3.01 kB │ map:  23.85 kB
-dist/provider-DSqqvDee.js   15.05 kB │ gzip:  6.17 kB │ map:  39.52 kB
-dist/index.js              196.19 kB │ gzip: 51.71 kB │ map: 547.91 kB
-[vite:dts] Declaration files built in 3639ms.
+dist/session.js          10.53 kB │ gzip:  3.24 kB │ map:  25.46 kB
+dist/index-BdTFKueB.js   38.34 kB │ gzip: 12.80 kB │ map:  81.00 kB
+dist/index.js           186.49 kB │ gzip: 49.14 kB │ map: 569.43 kB
+[vite:dts] Declaration files built in 3504ms.
 
-✓ built in 5.20s
+✓ built in 5.59s
 
-> @cartridge/controller@0.13.4 build:node /home/runner/work/controller/controller/packages/controller
+> @cartridge/controller@0.13.6 build:node /home/runner/work/controller/controller/packages/controller
 > tsup --config tsup.node.config.ts
 
 CLI Building entry: src/node/index.ts
@@ -34,16 +54,16 @@ computing gzip size...
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-"constants", "getChecksumAddress" and "shortString" are imported from external module "starknet" but never used in "dist/node/index.cjs".
+"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.
-"constants", "getChecksumAddress" and "shortString" are imported from external module "starknet" but never used in "dist/node/index.js".
-CJS dist/node/index.cjs     23.22 KB
-CJS dist/node/index.cjs.map 54.43 KB
-CJS ⚡️ Build success in 249ms
-ESM dist/node/index.js     22.43 KB
-ESM dist/node/index.js.map 54.20 KB
-ESM ⚡️ Build success in 250ms
+ESM dist/node/index.js     23.50 KB
+ESM dist/node/index.js.map 56.57 KB
+ESM ⚡️ Build success in 323ms
+CJS dist/node/index.cjs     24.40 KB
+CJS dist/node/index.cjs.map 56.82 KB
+CJS ⚡️ Build success in 324ms
 DTS Build start
-DTS ⚡️ Build success in 3079ms
-DTS dist/node/index.d.ts  5.98 KB
-DTS dist/node/index.d.cts 5.98 KB
+DTS ⚡️ Build success in 3326ms
+DTS dist/node/index.d.ts  6.42 KB
+DTS dist/node/index.d.cts 6.42 KB

package/HEADLESS_MODE.md

@@ -0,0 +1,113 @@
+# Headless Mode Guide
+
+## Overview
+
+Headless mode enables programmatic authentication with the Cartridge Controller SDK without displaying any UI. You trigger headless mode by passing a `username` and `signer` to `connect(...)`.
+
+```
+Controller SDK → Keychain iframe (hidden) → Backend API
+```
+
+**Key Points**
+- The keychain iframe still exists, but the modal is not opened.
+- The SDK passes the connect request to keychain over Penpal.
+- Keychain executes the same authentication logic as the UI flow.
+- No duplicated auth logic in the SDK.
+
+## Usage
+
+### Basic (Passkey / WebAuthn)
+
+```ts
+import Controller from "@cartridge/controller";
+
+const controller = new Controller({
+  defaultChainId: "SN_SEPOLIA",
+});
+
+await controller.connect({
+  username: "alice",
+  signer: "webauthn",
+});
+```
+
+### Password
+
+```ts
+await controller.connect({
+  username: "alice",
+  signer: "password",
+  password: "correct horse battery staple",
+});
+```
+
+### OAuth / EVM / WalletConnect
+
+```ts
+// Google / Discord
+await controller.connect({ username: "alice", signer: "google" });
+await controller.connect({ username: "alice", signer: "discord" });
+
+// EVM wallets
+await controller.connect({ username: "alice", signer: "metamask" });
+await controller.connect({ username: "alice", signer: "rabby" });
+await controller.connect({ username: "alice", signer: "phantom-evm" });
+
+// WalletConnect
+await controller.connect({ username: "alice", signer: "walletconnect" });
+```
+
+## Supported Auth Options
+
+Headless mode supports all **implemented** auth options:
+- `webauthn`
+- `password`
+- `google`
+- `discord`
+- `walletconnect`
+- `metamask`
+- `rabby`
+- `phantom-evm`
+
+## Handling Session Approval
+
+If policies are unverified or include approvals, Keychain will prompt for
+session approval **after** authentication. In that case, `connect` will open
+the approval UI and resolve once the session is approved.
+
+```ts
+const account = await controller.connect({
+  username: "alice",
+  signer: "webauthn",
+});
+
+console.log("Session approved:", account.address);
+```
+If you want to react to connection state changes, subscribe to the standard
+wallet events (for example `accountsChanged`) or just await `connect(...)` and
+update your app state afterwards.
+
+## Error Handling
+
+The SDK provides specific error classes for headless mode:
+
+```ts
+import {
+  HeadlessAuthenticationError,
+} from "@cartridge/controller";
+
+try {
+  await controller.connect({ username: "alice", signer: "webauthn" });
+} catch (error) {
+  if (error instanceof HeadlessAuthenticationError) {
+    // Auth failed (invalid credentials, signer mismatch, etc.)
+  }
+}
+```
+
+## Notes
+
+- Headless mode uses the **existing signers** on the controller for the given username.
+- For passkeys, the account must already have a WebAuthn signer registered.
+- If policies are unverified or include approvals, Keychain will request
+  explicit approval after authentication.

package/dist/controller.d.ts

@@ -1,8 +1,9 @@
 import { Policy } from '@cartridge/presets';
+import { WalletWithStarknetFeatures } from '@starknet-io/get-starknet-wallet-standard/features';
 import { AddStarknetChainParameters } from '@starknet-io/types-js';
 import { WalletAccount } from 'starknet';
 import { default as BaseProvider } from './provider';
-import { AuthOptions, ControllerOptions, ProfileContextTypeVariant, OpenOptions, StarterpackOptions } from './types';
+import { AuthOptions, ConnectOptions, ControllerOptions, ProfileContextTypeVariant, OpenOptions, StarterpackOptions } from './types';
 export default class ControllerProvider extends BaseProvider {
     private keychain?;
     private options;
@@ -15,7 +16,7 @@ export default class ControllerProvider extends BaseProvider {
     constructor(options?: ControllerOptions);
     logout(): Promise<void>;
     probe(): Promise<WalletAccount | undefined>;
-    connect(signupOptions?: AuthOptions): Promise<WalletAccount | undefined>;
+    connect(options?: AuthOptions | ConnectOptions): Promise<WalletAccount | undefined>;
     switchStarknetChain(chainId: string): Promise<boolean>;
     addStarknetChain(_chain: AddStarknetChainParameters): Promise<boolean>;
     disconnect(): Promise<void>;
@@ -23,6 +24,7 @@ export default class ControllerProvider extends BaseProvider {
     openProfileTo(to: string): Promise<void>;
     openProfileAt(at: string): Promise<void>;
     openSettings(): void;
+    close(): Promise<void>;
     revoke(origin: string, _policy: Policy[]): Promise<void> | null;
     rpcUrl(): string;
     username(): Promise<string> | undefined;
@@ -33,6 +35,11 @@ export default class ControllerProvider extends BaseProvider {
         transactionHash: string;
     } | undefined>;
     delegateAccount(): Promise<string | null>;
+    /**
+     * Returns a wallet standard interface for the controller.
+     * This allows using the controller with libraries that expect the wallet standard interface.
+     */
+    asWalletStandard(): WalletWithStarknetFeatures;
     /**
      * Opens the keychain in standalone mode (first-party context) for authentication.
      * This establishes first-party storage, enabling seamless iframe access across all games.

package/dist/errors.d.ts

@@ -1,3 +1,13 @@
 export declare class NotReadyToConnect extends Error {
     constructor();
 }
+export declare class HeadlessAuthenticationError extends Error {
+    cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+export declare class InvalidCredentialsError extends HeadlessAuthenticationError {
+    constructor(credentialType: string);
+}
+export declare class HeadlessModeNotSupportedError extends Error {
+    constructor(operation: string);
+}

package/dist/iframe/security.d.ts

@@ -0,0 +1,10 @@
+export declare function isLocalhostHostname(hostname: string): boolean;
+/**
+ * Restrict iframe targets to HTTPS in production, while still allowing local HTTP dev.
+ */
+export declare function validateKeychainIframeUrl(url: URL): void;
+/**
+ * Build a conservative allow list for iframe feature policy.
+ * Local network access is only needed for localhost development.
+ */
+export declare function buildIframeAllowList(url: URL): string;