refactor: replace WASM dependency in SessionProvider with pure TypeScript

[kronosapiens]

Closes #2518

This PR integrates the TS implementation of the SessionProvider from StarkZap, dropping the WASM dependency from controller-rs and unlocking React Native integration.

Summary

• Replaces all @cartridge/controller-wasm imports in the session/node paths with pure TypeScript implementations using only starknet.js primitives
• Adds 9 new files under packages/controller/src/session/internal/ implementing signerToGuid, Poseidon merkle trees, SNIP-9 v2 outside execution signing, session token serialization, and GraphQL subscription polling
• Swaps imports in 6 existing files (session/provider.ts, session/account.ts, session/index.ts, node/provider.ts, node/account.ts, utils.ts) — no public API changes
• Replaces localeCompare with byte-order string comparison in toWasmPolicies to ensure deterministic policy sorting across locales
• Removes @cartridge/controller-wasm as a dependency in package/controller

Benefits

• Bundle size: Replaces 3.7MB of WASM binaries (2.5MB controller + 1.2MB session) with 28KB of JavaScript. Every bundler that touches controller no longer needs to handle WASM compilation or require vite-plugin-wasm/vite-plugin-top-level-await.
• Debuggability: The WASM version returns opaque error codes (e.g. {"code":131}). The TS version gives readable stack traces and can be debugged with a console.log and a rebuild. Every developer who hits a session issue benefits.
• Platform compatibility: WASM is not supported in React Native, and requires special bundler plugins in every consuming project. The TS version is plain ES modules — it works everywhere.
• Deployment coupling: The WASM package is versioned independently (@cartridge/controller-wasm@0.10.0). Fixing a session signing bug currently requires: fix in Rust → build WASM → publish package → bump version in controller → release. With TS it's one PR.
• Auditability: The team and integrators can read and review the signing logic in TypeScript. The WASM binary is opaque — for security-sensitive code like session token construction, readability matters.

Key files

New files under packages/controller/src/session/internal/ (93% statement / 94% line coverage):

File	Purpose	Stmts	Lines
execution.ts	Builds and signs SNIP-9 v2 outside execution payloads. Handles nonce generation, time bounds, call serialization, and session token construction with Stark curve signing.	99%	99%
merkle.ts	Computes Poseidon Merkle trees and proofs over session policies. Supports CallPolicy, TypedDataPolicy, and ApprovalPolicy leaf types.	99%	98%
utils.ts	Felt normalization, selector computation, contract address padding, and signerToGuid (Poseidon hash of domain + public key).	100%	100%
account.ts	CartridgeSessionAccount — holds session credentials and submits signed payloads to the Cartridge RPC via cartridge_addExecuteOutsideTransaction.	94%	94%
subscribe.ts	Polls the Cartridge GraphQL API for session registration confirmation with exponential backoff and timeout.	93%	97%
errors.ts	Error types for session failures: SessionProtocolError, SessionTimeoutError, and SNIP-9 compatibility detection.	80%	83%
types.ts	Shared type definitions: CallPolicy, TypedDataPolicy, ApprovalPolicy, Session.	—	—

Notes

Decoupling from controller-rs

This creates a second implementation of session signing alongside controller-rs, which is still consumed by the keychain. The two implementations both conform to the same on-chain session protocol (SNIP-9 v2 + Cartridge session token format). Correctness is enforced by the contract at submission time — if either implementation produces a malformed payload, it is rejected by the RPC. If the protocol changes, both implementations will need to be updated.

Behavioral change: execute() fallback removed

The old code silently fell back to this.controller.execute() (direct invocation) when executeFromOutside() failed. This fallback could never succeed under Cartridge's current session registration flow (due to required guardian signature replacement), so the new code throws a SessionProtocolError with a clear message instead.

References

• Original WASM implementation: cartridge-gg/controller-rs
• TypeScript reference implementation: StarkZap session signer

Test plan

• All 111 controller tests pass (52 existing + 59 new)
• All 407 keychain tests pass
• Connector test passes
• Build succeeds (pnpm build)
• Lint and format checks pass (pnpm lint)
• Verified session flow end-to-end on iOS (Capacitor) against Sepolia
• Verify executeFromOutside produces payloads accepted by Cartridge relayer

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
controller-example-next	Ready	Preview	Apr 21, 2026 2:04pm
keychain	Ready	Preview	Apr 21, 2026 2:04pm
keychain-storybook	Ready	Preview	Apr 21, 2026 2:04pm

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 21.30%. Comparing base (00e9912) to head (e6b5001).
⚠️ Report is 13 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2542      +/-   ##
==========================================
- Coverage   21.41%   21.30%   -0.11%     
==========================================
  Files         339      342       +3     
  Lines       37969    38436     +467     
  Branches     1216     1224       +8     
==========================================
+ Hits         8131     8190      +59     
- Misses      29819    30227     +408     
  Partials       19       19              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[kronosapiens]

Confirming that this code has been manually exercised using the Capacitor example in /examples/capacitor and can correctly register sessions and make transactions.

https://sepolia.voyager.online/contract/0x034f27844fd897c18be6f697ba20603d61d4c26e46a9519e0131a31b9f3f1af3