fix: SessionProvider preset support and address normalization

[kronosapiens]

Summary

Fixes #2399.
Addresses session/not-registered errors caused by policy hash divergence between the SDK and keychain.

SDK changes (@cartridge/controller)

• Add preset and shouldOverridePresetPolicies to SessionOptions: Developers can now pass preset: "my-game" instead of manually duplicating policies.
  Preset policies are resolved via loadConfig() from @cartridge/presets, matching the keychain's behavior.
  Policy precedence matches ControllerProvider: preset wins unless shouldOverridePresetPolicies: true.
• Consolidate async init into _init(): Preset resolution, session retrieval from storage, and signer key setup all happen in a single eagerly-started async method.
  Public methods (username, probe, connect) simply await this._ready.
• Normalize addresses in toWasmPolicies: Applies getChecksumAddress() to contract targets before hashing, preventing divergence from inconsistent address casing.
• Extract getPresetSessionPolicies utility: Shared between SessionProvider and the keychain's getConfigChainPolicies, replacing ~25 lines of defensive type narrowing with a clean helper.
• Warn on silent policy drop: When both preset and policies are provided without the override flag, a console.warn is logged (previously policies were silently ignored in ControllerProvider).
• Send preset in keychain URL: When preset is used, connect() sends &preset= instead of &policies=, so the keychain resolves the same policies from the same source.

Keychain changes

• Gate rendering on isPoliciesResolved in Authentication: The Authentication wrapper now waits for preset policies to fully resolve before rendering child routes.
  This replaces scattered isPoliciesResolved guards that were previously in ConnectRoute and eliminates race conditions where components render before async preset policy resolution completes.

Root cause

When a developer configured presets and used SessionProvider, the keychain would resolve policies from the preset while the SDK used the developer's manually-passed policies.
If these differed (or if addresses had different casing), the session hash would diverge, producing session/not-registered errors.

Design note

Preset resolution is async (loadConfig fetches from the network), but JS constructors can't be async.
The _init() method is eagerly started in the constructor and stores its promise as _ready.
A cleaner alternative would be a static factory method (SessionProvider.create(options)), but that's a breaking API change — worth considering in a future major version.

Follow-up

• Apply same preset support to TelegramProvider and Node.js SessionProvider

Test plan

• All 45 controller unit tests pass (including updated toWasmPolicies tests)
• All 356 keychain tests pass
• tsc --noEmit passes with zero errors
• Full monorepo build succeeds
• Lint and format checks pass
• Manual verification with a preset-configured app using SessionProvider

🤖 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	Feb 11, 2026 10:09pm
keychain	Ready	Preview	Feb 11, 2026 10:09pm
keychain-storybook	Ready	Preview	Feb 11, 2026 10:09pm

[codecov]

Codecov Report

❌ Patch coverage is 0% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 20.57%. Comparing base (fb3c5f6) to head (5dfb619).
⚠️ Report is 5 commits behind head on main.

Files with missing lines	Patch %	Lines
packages/keychain/src/hooks/connection.ts	0.00%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2401      +/-   ##
==========================================
+ Coverage   19.81%   20.57%   +0.76%     
==========================================
  Files         327      316      -11     
  Lines       33133    33288     +155     
  Branches      883      970      +87     
==========================================
+ Hits         6564     6849     +285     
+ Misses      26557    26425     -132     
- Partials       12       14       +2     

☔ 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.

[broody]

Works great!

Did more work after initial review

[broody]

LGTM

[claude]

Claude finished @kronosapiens's task —— View job

---

Analyzing controller PR changes and updating documentation

I'll analyze the merged PR #2401 changes and update the documentation in the docs repository accordingly.

Tasks:

• Explore docs-repo directory structure to understand current documentation
• Review the PR changes to identify user-facing API changes
• Determine what documentation needs updating for SessionProvider preset support
• Update or create appropriate documentation files
• Commit and push changes if needed

Analysis of Changes

Based on my review of the merged PR #2401, the main changes that need documentation are:

1. New SessionOptions parameters:

   • preset?: string - Allows passing preset name instead of manual policies
   • shouldOverridePresetPolicies?: boolean - Controls precedence between preset and manually passed policies

2. Policy precedence logic: Matches ControllerProvider behavior where preset wins unless shouldOverridePresetPolicies is true

3. Address normalization: Internal improvement to prevent session/not-registered errors

4. Warning on policy conflicts: Console warning when both preset and policies are provided without override flag

Documentation Updates Made

I've successfully updated /docs-repo/src/pages/controller/sessions.md with comprehensive documentation for the new SessionProvider preset support:

Updated SessionOptions interface - Added the new preset and shouldOverridePresetPolicies parameters with clear descriptions

Added new "Using Presets with SessionProvider" section covering:

• Basic preset usage examples
• Policy precedence rules (preset vs manual policies)
• Override behavior with shouldOverridePresetPolicies flag
• Benefits of using presets (consistency, verification, maintenance, error prevention)

Updated existing examples - Changed authentication configuration example to showcase preset usage instead of manual policies

Updated manual session processing example - Shows preset usage in native app context

The documentation now accurately reflects the new SessionProvider capabilities added in PR #2401. I'm unable to commit these changes to the docs repository due to git configuration restrictions, but the files have been successfully updated in the docs-repo directory.