@cartridge/controller 0.13.3 → 0.13.5

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

@@ -1,18 +1,38 @@
 
-> @cartridge/controller@0.13.3 build:deps /home/runner/work/controller/controller/packages/controller
+> @cartridge/controller@0.13.5 build:deps /home/runner/work/controller/controller/packages/controller
 > pnpm build
 
 
-> @cartridge/controller@0.13.3 build /home/runner/work/controller/controller/packages/controller
+> @cartridge/controller@0.13.5 build /home/runner/work/controller/controller/packages/controller
 > pnpm build:browser && pnpm build:node
 
 
-> @cartridge/controller@0.13.3 build:browser /home/runner/work/controller/controller/packages/controller
+> @cartridge/controller@0.13.5 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-bC9cKItb.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 3652ms.
+dist/session.js             10.19 kB │ gzip:  3.09 kB │ map:  23.94 kB
+dist/provider-NKp7_oNj.js   15.63 kB │ gzip:  6.32 kB │ map:  41.81 kB
+dist/index.js              208.69 kB │ gzip: 55.04 kB │ map: 607.52 kB
+[vite:dts] Declaration files built in 3567ms.
 
-✓ built in 5.26s
+✓ built in 5.63s
 
-> @cartridge/controller@0.13.3 build:node /home/runner/work/controller/controller/packages/controller
+> @cartridge/controller@0.13.5 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".
 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 294ms
-ESM dist/node/index.js     22.43 KB
-ESM dist/node/index.js.map 54.20 KB
-ESM ⚡️ Build success in 295ms
+ESM dist/node/index.js     23.43 KB
+ESM dist/node/index.js.map 55.93 KB
+ESM ⚡️ Build success in 320ms
+CJS dist/node/index.cjs     24.32 KB
+CJS dist/node/index.cjs.map 56.16 KB
+CJS ⚡️ Build success in 320ms
 DTS Build start
-DTS ⚡️ Build success in 2999ms
-DTS dist/node/index.d.ts  5.98 KB
-DTS dist/node/index.d.cts 5.98 KB
+DTS ⚡️ Build success in 3096ms
+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.3 build /home/runner/work/controller/controller/packages/controller
+> @cartridge/controller@0.13.5 build /home/runner/work/controller/controller/packages/controller
 > pnpm build:browser && pnpm build:node
 
 
-> @cartridge/controller@0.13.3 build:browser /home/runner/work/controller/controller/packages/controller
+> @cartridge/controller@0.13.5 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-bC9cKItb.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 3577ms.
+dist/session.js             10.19 kB │ gzip:  3.09 kB │ map:  23.94 kB
+dist/provider-NKp7_oNj.js   15.63 kB │ gzip:  6.32 kB │ map:  41.81 kB
+dist/index.js              208.69 kB │ gzip: 55.04 kB │ map: 607.52 kB
+[vite:dts] Declaration files built in 3532ms.
 
-✓ built in 5.29s
+✓ built in 5.65s
 
-> @cartridge/controller@0.13.3 build:node /home/runner/work/controller/controller/packages/controller
+> @cartridge/controller@0.13.5 build:node /home/runner/work/controller/controller/packages/controller
 > tsup --config tsup.node.config.ts
 
 CLI Building entry: src/node/index.ts
@@ -37,13 +57,13 @@ computing gzip size...
 "constants", "getChecksumAddress" 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".
-ESM dist/node/index.js     22.43 KB
-ESM dist/node/index.js.map 54.20 KB
-ESM ⚡️ Build success in 305ms
-CJS dist/node/index.cjs     23.22 KB
-CJS dist/node/index.cjs.map 54.43 KB
-CJS ⚡️ Build success in 306ms
+ESM dist/node/index.js     23.43 KB
+ESM dist/node/index.js.map 55.93 KB
+ESM ⚡️ Build success in 289ms
+CJS dist/node/index.cjs     24.32 KB
+CJS dist/node/index.cjs.map 56.16 KB
+CJS ⚡️ Build success in 289ms
 DTS Build start
-DTS ⚡️ Build success in 3078ms
-DTS dist/node/index.d.ts  5.98 KB
-DTS dist/node/index.d.cts 5.98 KB
+DTS ⚡️ Build success in 3292ms
+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/LICENSE

@@ -0,0 +1,16 @@
+Copyright Cartridge Gaming Company 2022. All rights reserved.
+
+You acknowledge and agree that Cartridge Gaming Company (“Cartridge”) (or Cartridge’s licensors) own all legal right, title and interest in and to the work, software, application, source code, documentation and any other documents in this repository (collectively, the “Program”), including any intellectual property rights which subsist in the Program (whether those rights happen to be registered or not, and wherever in the world those rights may exist), whether in source code or any other form.
+
+Subject to the limited license below, you may not (and you may not permit anyone else to) distribute, publish, copy, modify, merge, combine with another program, create derivative works of, reverse engineer, decompile or otherwise attempt to extract the source code of, the Program or any part thereof, except that you may contribute to this repository.
+
+You are granted a non-exclusive, non-transferable, non-sublicensable license to distribute, publish, copy, modify, merge, combine with another program or create derivative works of the Program (such resulting program, collectively, the “Resulting Program”) solely for Non-Commercial Use as long as you:
+ 1. give prominent notice (“Notice”) with each copy of the Resulting Program that the Program is used in the Resulting Program and that the Program is the copyright of Cartridge; and
+ 2. subject the Resulting Program and any distribution, publication, copy, modification, merger therewith, combination with another program or derivative works thereof to the same Notice requirement and Non-Commercial Use restriction set forth herein.
+
+“Non-Commercial Use” means each use as described in clauses (1)-(3) below, as reasonably determined by Cartridge in its sole discretion: 
+ 1. personal use for research, personal study, private entertainment, hobby projects or amateur pursuits, in each case without any anticipated commercial application;
+ 2. use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization or government institution; or
+ 3. the number of monthly active users of the Resulting Program across all versions thereof and platforms globally do not exceed 10,000 at any time.
+
+You will not use any trade mark, service mark, trade name, logo of Cartridge or any other company or organization in a way that is likely or intended to cause confusion about the owner or authorized user of such marks, names or logos.

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;

package/dist/index.d.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';